@empirical-gauzza/cli 1.0.9 → 1.0.11

package/bin/empirical.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 

package/lib/constants.js

@@ -121,9 +121,10 @@ Runs the interactive installer to connect Empirical memory to your AI coding CLI
    instruction files are left unchanged
 5. Offers optional browser OAuth login for CLI use, optional headless/API-key bootstrap for
    automation, containers, and external runtimes, and optional work-history/scar-tissue guidance
-6. For Claude, installs a \`SessionStart\` hook in \`~/.claude/settings.json\` that calls the
-   \`empirical\` CLI directly once per session — deterministic baseline context that doesn't
-   depend on the model deciding to call a tool. Codex/Copilot have no equivalent hook mechanism.
+6. Installs a \`SessionStart\` hook for each selected client that calls the \`empirical\` CLI
+   directly once per session — deterministic baseline context that doesn't depend on the model
+   deciding to call a tool. Claude: \`~/.claude/settings.json\`. Codex: \`<CODEX_HOME>/hooks.json\`
+   (defaults to \`~/.codex\`). Copilot: \`~/.copilot/hooks/empirical-session-start.json\`.
 7. Installs the native \`empirical-memory\` plugin for each selected client. The plugin owns
    the Empirical MCP connection and all agent-facing Skills; the CLI does not generate duplicate
    \`SKILL.md\` or \`EMPIRICAL_SKILL.md\` files.

package/lib/installWizard.js

@@ -1,11 +1,11 @@
 'use strict';
 
-const { log, warn, uiHeader, uiQuestion, uiSuccess, uiWarn, uiDim, uiLink, ask, askYesNo, parseSelection, formatHeadlessErrorHint } = require('./ui');
-const { getEnv } = require('./env');
+const { log, warn, uiHeader, uiQuestion, uiSuccess, uiWarn, uiDim, uiLink, ask, askYesNo, parseSelection, formatHeadlessErrorHint } = require('./ui');
+const { getEnv } = require('./env');
 const { summarizeProcessOutput } = require('./fsUtils');
 const {
   EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_URL,
-  getCliVersion, deriveBaseUrlFromMcpUrl
+  getCliVersion, deriveBaseUrlFromMcpUrl
 } = require('./constants');
 const {
   readStoredOAuthClient, writeStoredOAuthClient, getLocalOAuthClientPath,
@@ -16,22 +16,22 @@ const {
   runMcpOAuthFlow, updateClaudeMcpServerAuth, resolveAccessToken
 } = require('./auth');
 const { performSync, printSyncSummary } = require('./skillSync');
-const {
-  INSTALL_PROMPT_OPTIONS_DEFAULTS, collectInstallerPromptOptions,
-} = require('./installers/promptBlocks');
+const {
+  INSTALL_PROMPT_OPTIONS_DEFAULTS, collectInstallerPromptOptions,
+} = require('./installers/promptBlocks');
 const { detectInstallTargets } = require('./installers/detect');
-const { installClaudeHooks } = require('./installers/hooks');
-const { runCodex } = require('./installers/codex');
-const { installNativePlugin, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
-const { policyFromInstallerOptions, savePolicy: persistPolicy } = require('./policyCommands');
-
-function pluginNamesForInstallerOptions(options = {}) {
-  const names = ['empirical-memory'];
-  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');
-  return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
-}
+const { installClaudeHooks, installCodexHooks, installCopilotHooks } = require('./installers/hooks');
+const { runCodex } = require('./installers/codex');
+const { installNativePlugin, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
+const { policyFromInstallerOptions, savePolicy: persistPolicy } = require('./policyCommands');
+
+function pluginNamesForInstallerOptions(options = {}) {
+  const names = ['empirical-memory'];
+  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');
+  return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
+}
 
 async function runInstallFlow() {
   log(uiHeader(`Empirical installer v${getCliVersion()}`));
@@ -74,17 +74,17 @@ async function runInstallFlow() {
     log('');
   }
 
-  let promptOptions;
-  let savePolicyEnabled;
+  let promptOptions;
+  let savePolicyEnabled;
 
   if (integrationMode === 2) {
-    // CLI-direct mode: skip MCP-specific installer questions
-    promptOptions = { ...INSTALL_PROMPT_OPTIONS_DEFAULTS };
-    savePolicyEnabled = true;
-  } else {
-    const promptSetup = await collectInstallerPromptOptions();
-    promptOptions = promptSetup.promptOptions;
-    savePolicyEnabled = promptSetup.savePolicy !== false;
+    // CLI-direct mode: skip MCP-specific installer questions
+    promptOptions = { ...INSTALL_PROMPT_OPTIONS_DEFAULTS };
+    savePolicyEnabled = true;
+  } else {
+    const promptSetup = await collectInstallerPromptOptions();
+    promptOptions = promptSetup.promptOptions;
+    savePolicyEnabled = promptSetup.savePolicy !== false;
   }
 
   log(uiHeader('Installer auth setup'));
@@ -95,8 +95,8 @@ async function runInstallFlow() {
   }
   const useHeadlessDefault = getEnv('EMPIRICAL_HEADLESS_DEFAULT', 'true').toLowerCase() !== 'false';
   const settingsUrl = `${installerBaseUrl.replace(/\/$/, '')}/app/settings`;
-  let headlessToken = null;
-  let policyAccessToken = null;
+  let headlessToken = null;
+  let policyAccessToken = null;
   try {
     const existingClient = readStoredOAuthClient();
     if (getEnv('EMPIRICAL_CLIENT_ID')) {
@@ -138,12 +138,12 @@ async function runInstallFlow() {
   }
   log('');
 
-  let shouldBootstrapHeadless = useHeadlessDefault;
-  if (process.stdin.isTTY) {
-    log('Optional credential setup:');
-    log('  Browser OAuth is the normal choice for interactive CLI use.');
-    log('  Headless bootstrap creates reusable credentials for CLI use, automation, containers, and external runtimes.');
-    log('  Headless bootstrap uses Settings client credentials (client ID + client secret).');
+  let shouldBootstrapHeadless = useHeadlessDefault;
+  if (process.stdin.isTTY) {
+    log('Optional credential setup:');
+    log('  Browser OAuth is the normal choice for interactive CLI use.');
+    log('  Headless bootstrap creates reusable credentials for CLI use, automation, containers, and external runtimes.');
+    log('  Headless bootstrap uses Settings client credentials (client ID + client secret).');
     log('  Client credentials are loaded from env/saved oauth-client.json, with prompt fallback.');
     log(`  Settings: ${uiLink(settingsUrl)}`);
     shouldBootstrapHeadless = await askYesNo('Bootstrap headless token now?', useHeadlessDefault);
@@ -192,31 +192,31 @@ async function runInstallFlow() {
         }
       }
     }
-  } else {
-    log('Headless auth: skipped by user choice. Interactive OAuth will be used when required.');
-    log('');
-  }
-
-  if ((integrationMode === 2 || integrationMode === 3) && !resolveAccessToken()) {
-    try {
-      log('CLI auth: no reusable credential found. Opening browser OAuth login...');
-      await runMcpOAuthFlow(installerBaseUrl);
-      log(uiSuccess('CLI OAuth session saved. Empirical CLI commands are ready to use.'));
-      log('');
-    } catch (error) {
-      warn(uiWarn(`CLI OAuth login failed: ${error.message}`));
-      warn('  CLI commands will need a credential later: run "empirical auth login".');
-      log('');
-    }
-  }
-
-  if (integrationMode !== 2) {
-    const preflight = await oauthPreflight(EMPIRICAL_MCP_URL);
-    if (!preflight.ok) {
-      warn(`OAuth preflight warning: ${preflight.message}`);
-      warn('Codex/Claude setup may fail until the hosted OAuth login page is updated.');
-      log('');
-    }
+  } else {
+    log('Headless auth: skipped by user choice. Interactive OAuth will be used when required.');
+    log('');
+  }
+
+  if ((integrationMode === 2 || integrationMode === 3) && !resolveAccessToken()) {
+    try {
+      log('CLI auth: no reusable credential found. Opening browser OAuth login...');
+      await runMcpOAuthFlow(installerBaseUrl);
+      log(uiSuccess('CLI OAuth session saved. Empirical CLI commands are ready to use.'));
+      log('');
+    } catch (error) {
+      warn(uiWarn(`CLI OAuth login failed: ${error.message}`));
+      warn('  CLI commands will need a credential later: run "empirical auth login".');
+      log('');
+    }
+  }
+
+  if (integrationMode !== 2) {
+    const preflight = await oauthPreflight(EMPIRICAL_MCP_URL);
+    if (!preflight.ok) {
+      warn(`OAuth preflight warning: ${preflight.message}`);
+      warn('Codex/Claude setup may fail until the hosted OAuth login page is updated.');
+      log('');
+    }
   }
 
   let failures = 0;
@@ -228,26 +228,40 @@ async function runInstallFlow() {
     const target = targets[index];
     log(uiHeader(`Step 2/2: Installing for ${target.label}...`));
     try {
-      if (integrationMode === 2) {
-        // CLI-direct: skip MCP registration; the native plugin owns guidance.
-        const pluginNames = pluginNamesForInstallerOptions(promptOptions);
-        installNativePlugin(target.id, pluginNames);
-        log(`  - ${target.label} native plugins installed: ${pluginNames.join(', ')}.`);
-        if (target.id === 'claude') {
-          try {
-            installClaudeHooks();
+      if (integrationMode === 2) {
+        // CLI-direct: skip MCP registration; the native plugin owns guidance.
+        const pluginNames = pluginNamesForInstallerOptions(promptOptions);
+        installNativePlugin(target.id, pluginNames);
+        log(`  - ${target.label} native plugins installed: ${pluginNames.join(', ')}.`);
+        if (target.id === 'claude') {
+          try {
+            installClaudeHooks(pluginNames);
           } catch (error) {
             warn(`  - Could not install Claude hooks for deterministic memory lookups: ${error.message}`);
           }
-        }
-        log(uiSuccess(`Done: ${target.label} (CLI-direct mode)`));
+        }
+        if (target.id === 'codex') {
+          try {
+            installCodexHooks(pluginNames);
+          } catch (error) {
+            warn(`  - Could not install Codex hooks for deterministic memory lookups: ${error.message}`);
+          }
+        }
+        if (target.id === 'copilot') {
+          try {
+            installCopilotHooks(pluginNames);
+          } catch (error) {
+            warn(`  - Could not install Copilot hooks for deterministic memory lookups: ${error.message}`);
+          }
+        }
+        log(uiSuccess(`Done: ${target.label} (CLI-direct mode)`));
       } else {
         // Mode 1 or 3: run MCP install normally
-        const pluginNames = pluginNamesForInstallerOptions(promptOptions);
-        const installResult = target.install(headlessToken, promptOptions, {
-          writeGlobalInstructions: false,
-          pluginNames
-        });
+        const pluginNames = pluginNamesForInstallerOptions(promptOptions);
+        const installResult = target.install(headlessToken, promptOptions, {
+          writeGlobalInstructions: false,
+          pluginNames
+        });
         log(uiSuccess(`Done: ${target.label}`));
         if (target.id === 'codex') {
           codexInstalled = true;
@@ -256,7 +270,7 @@ async function runInstallFlow() {
         if (target.id === 'claude') {
           claudeInstalled = true;
         }
-      }
+      }
     } catch (error) {
       failures += 1;
       warn(uiWarn(`Failed: ${target.label} - ${error.message}`));
@@ -282,11 +296,11 @@ async function runInstallFlow() {
       } else {
         const detail = summarizeProcessOutput(loginResult);
         warn(uiWarn(`Codex MCP authentication returned a non-zero status${detail ? `: ${detail}` : '.'}`));
-        warn('Re-run `empirical install` to retry automatic authentication.');
+        warn('Re-run `empirical install` to retry automatic authentication.');
       }
     } catch (error) {
       warn(uiWarn(`Codex MCP authentication failed: ${error.message}`));
-      warn('Re-run `empirical install` to retry automatic authentication.');
+      warn('Re-run `empirical install` to retry automatic authentication.');
     }
     log('');
   }
@@ -294,7 +308,7 @@ async function runInstallFlow() {
   // Offer to authenticate Empirical MCP after Claude installation.
   // Prefer the permanent API key from the headless bootstrap (never expires)
   // over a short-lived JWT from the browser OAuth flow.
-  if (claudeInstalled && process.stdin.isTTY) {
+  if (claudeInstalled && process.stdin.isTTY) {
     log(uiHeader('Empirical MCP authentication'));
     const permanentToken = headlessToken?.apiKey || '';
     if (permanentToken) {
@@ -310,45 +324,45 @@ async function runInstallFlow() {
       try {
         log('');
         log(uiQuestion('Authenticating Empirical MCP...'));
-        const mcpToken = await runMcpOAuthFlow(installerBaseUrl);
-        policyAccessToken = mcpToken.accessToken;
-        updateClaudeMcpServerAuth(EMPIRICAL_MCP_NAME, mcpToken.accessToken);
+        const mcpToken = await runMcpOAuthFlow(installerBaseUrl);
+        policyAccessToken = mcpToken.accessToken;
+        updateClaudeMcpServerAuth(EMPIRICAL_MCP_NAME, mcpToken.accessToken);
         log(uiSuccess('Empirical MCP authenticated successfully in Claude!'));
-        log('  Note: this OAuth token expires in ~30 days. Re-run the installer with');
-        log('  your Settings client credentials to get a permanent credential instead.');
+        log('  Note: this OAuth token expires in ~30 days. Re-run the installer with');
+        log('  your Settings client credentials to get a permanent credential instead.');
       } catch (error) {
         warn(uiWarn(`MCP authentication failed: ${error.message}`));
         warn('You can authenticate later from Claude Code by using the /mcp command.');
       }
     }
-    log('');
-  }
-
-  // Persist the selected behavior after the installer has had a chance to complete OAuth/MCP
-  // authentication. In MCP-only mode, authentication happens after native installation.
-  try {
-    const accessToken = resolveAccessToken() || policyAccessToken;
-    if (accessToken && savePolicyEnabled) {
-      await persistPolicy(policyFromInstallerOptions(promptOptions), accessToken);
-      log(uiSuccess('Empirical behavior policy saved for native skills.'));
-    } else if (accessToken) {
-      log('Empirical behavior policy not saved by user choice; native skills will use safe defaults.');
-    } else {
-      warn('Empirical behavior policy was not saved: no authenticated CLI credential is available yet.');
-    }
-    log('');
-  } catch (error) {
-    warn(uiWarn(`Empirical behavior policy could not be saved: ${error.message}`));
-    log('');
-  }
+    log('');
+  }
+
+  // Persist the selected behavior after the installer has had a chance to complete OAuth/MCP
+  // authentication. In MCP-only mode, authentication happens after native installation.
+  try {
+    const accessToken = resolveAccessToken() || policyAccessToken;
+    if (accessToken && savePolicyEnabled) {
+      await persistPolicy(policyFromInstallerOptions(promptOptions), accessToken);
+      log(uiSuccess('Empirical behavior policy saved for native skills.'));
+    } else if (accessToken) {
+      log('Empirical behavior policy not saved by user choice; native skills will use safe defaults.');
+    } else {
+      warn('Empirical behavior policy was not saved: no authenticated CLI credential is available yet.');
+    }
+    log('');
+  } catch (error) {
+    warn(uiWarn(`Empirical behavior policy could not be saved: ${error.message}`));
+    log('');
+  }
 
   // US-011: independent of whether any Kit exists or `kit use` has ever been run, also sync
   // the active device's resolved (builtin ∪ Default Kit ∪ active named Kit) Skill set into
   // every detected agent's skill directory now, so a brand-new device gets the Default Kit's
   // authored Skills (if any exist yet — likely none for a fresh account, which is fine; the
   // sync just writes zero non-builtin Skills) immediately. This does NOT touch the
-  // Native plugin installation above owns the empirical-memory Skill. The generalized Kit
-  // writer below must continue to exclude the builtin placeholder with the same name.
+  // Native plugin installation above owns the empirical-memory Skill. The generalized Kit
+  // writer below must continue to exclude the builtin placeholder with the same name.
   try {
     const syncAccessToken = resolveAccessToken();
     if (syncAccessToken) {
@@ -370,13 +384,13 @@ async function runInstallFlow() {
     log('');
   }
 
-  const completionMessage = integrationMode === 2
-    ? 'Install complete. Next time you open the selected CLI(s), Empirical CLI commands should be available.'
-    : integrationMode === 3
-      ? 'Install complete. Next time you open the selected CLI(s), Empirical MCP and CLI commands should be available.'
-      : 'Install complete. Next time you open the selected CLI(s), Empirical MCP should be available.';
-  log(uiSuccess(completionMessage));
-}
+  const completionMessage = integrationMode === 2
+    ? 'Install complete. Next time you open the selected CLI(s), Empirical CLI commands should be available.'
+    : integrationMode === 3
+      ? 'Install complete. Next time you open the selected CLI(s), Empirical MCP and CLI commands should be available.'
+      : 'Install complete. Next time you open the selected CLI(s), Empirical MCP should be available.';
+  log(uiSuccess(completionMessage));
+}
 
 module.exports = {
   runInstallFlow

package/lib/installers/claude.js

@@ -22,15 +22,19 @@ function isClaudeServerConfigured(name) {
 function installClaude(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
   log('  - Claude global guidance file unchanged; native plugin guidance is authoritative.');
 
+  // installNativePlugin throws if the plugin install/update genuinely fails (see
+  // assertPluginInstallSucceeded in nativePlugin.js) - hooks are only installed AFTER this
+  // succeeds, never before, so a failed/skipped plugin install never leaves an orphaned hook
+  // pointing at a plugin that isn't actually present.
+  installNativePlugin('claude', installOptions.pluginNames);
+  log(`  - Claude native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
+
   try {
-    installClaudeHooks();
+    installClaudeHooks(installOptions.pluginNames);
   } catch (error) {
     warn(`  - Could not install Claude hooks for deterministic memory lookups: ${error.message}`);
   }
 
-  installNativePlugin('claude', installOptions.pluginNames);
-  log(`  - Claude native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
-
   if (!commandExists('claude')) {
     warn('  - Claude CLI not found on PATH. Skipped Claude MCP registration.');
     return;

package/lib/installers/codex.js

@@ -7,6 +7,7 @@ const {
   EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL
 } = require('../constants');
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
+const { installCodexHooks } = require('./hooks');
 const { installNativePlugin } = require('./nativePlugin');
 
 function runCodex(args, options = {}) {
@@ -21,9 +22,18 @@ function isCodexServerConfigured(name) {
 function installCodex(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
   log('  - Codex global AGENTS instructions unchanged; native plugin guidance is authoritative.');
 
+  // installNativePlugin throws on genuine failure (see assertPluginInstallSucceeded in
+  // nativePlugin.js) - hooks install only AFTER this succeeds, never before, so a failed/skipped
+  // plugin install never leaves an orphaned hook pointing at a plugin that isn't present.
   installNativePlugin('codex', installOptions.pluginNames);
   log(`  - Codex native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
 
+  try {
+    installCodexHooks(installOptions.pluginNames);
+  } catch (error) {
+    warn(`  - Could not install Codex hooks for deterministic memory lookups: ${error.message}`);
+  }
+
   if (!commandExists('codex')) {
     warn('  - Codex CLI not found on PATH. Skipped Codex MCP registration.');
     return;

package/lib/installers/copilot.js

@@ -10,6 +10,7 @@ const {
   EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL, COPILOT_OAUTH_CLIENT_ID
 } = require('../constants');
 const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
+const { installCopilotHooks } = require('./hooks');
 const { installNativePlugin } = require('./nativePlugin');
 
 function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
@@ -62,9 +63,18 @@ function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DE
 
   log('  - Copilot global instructions unchanged; native plugin guidance is authoritative.');
 
+  // installNativePlugin throws on genuine failure (see assertPluginInstallSucceeded in
+  // nativePlugin.js) - hooks install only AFTER this succeeds, never before, so a failed/skipped
+  // plugin install never leaves an orphaned hook pointing at a plugin that isn't present.
   installNativePlugin('copilot', installOptions.pluginNames);
   log(`  - Copilot native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
 
+  try {
+    installCopilotHooks(installOptions.pluginNames);
+  } catch (error) {
+    warn(`  - Could not install Copilot hooks for deterministic memory lookups: ${error.message}`);
+  }
+
   log('  - Copilot MCP config updated.');
   if (storedClient?.clientId) {
     log(`  - Copilot OAuth client loaded from ${getLocalOAuthClientPath()}.`);

package/lib/installers/hooks.js

@@ -4,11 +4,73 @@ const os = require('os');
 const path = require('path');
 const { log } = require('../ui');
 const { ensureDir, writeFile, readJsonIfExists } = require('../fsUtils');
+const { normalizePluginNames } = require('./nativePlugin');
 
 const CLAUDE_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
 'use strict';
 
 var spawnSync = require('child_process').spawnSync;
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+// Diagnostic breadcrumb log: this hook's own stdout is only visible to Claude Code's SessionStart
+// machinery, not to a human debugging "did this actually fire" after the fact. Every run appends
+// one line here (bounded — see trimLogIfLarge) regardless of success/failure, so firing can be
+// verified by checking file growth/timestamps after starting or resuming a session, without
+// depending on server-side analytics that don't currently tag hook-originated calls.
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break session start.
+  }
+}
+
+// On Windows, npm's global "empirical" command is a .cmd shim, and .cmd/.bat files can only be
+// executed via the OS shell (cmd.exe), never as a native process — this is an OS constraint, not
+// a Node quirk. But spawnSync's shell:true path joins argv into a single command-line string for
+// cmd.exe to reparse, and Node does not escape special shell characters (spaces, commas, etc.) in
+// that join for you. A --match value like "project context, conventions, recent decisions, user
+// preferences" gets mangled by that reparse, silently truncating the search query and returning
+// far fewer/worse matches than the same query run without a shell in between. The fix: resolve
+// the shim's REAL target (a plain .js file) and invoke that directly via node.exe with shell:false
+// — node.exe is a true native executable, so no shell/reparsing step exists to mangle args.
+function resolveEmpiricalEntryPoint() {
+  if (process.platform !== 'win32') {
+    // POSIX global installs are usually a symlink straight to the JS entry (or a shebang script)
+    // — spawnSync already runs these directly without a shell, so no mangling risk exists there.
+    return null;
+  }
+  try {
+    // Parse the .cmd shim itself rather than hardcoding an npm package scope: the published
+    // package has already been renamed once (was the empirical scope, now a different scope
+    // entirely - the old one is 404 on the registry), so hardcoding either name is a guaranteed
+    // future break. npm-generated shims all reference their target relative to dp0 (the shim's
+    // own directory) as a node_modules-rooted path ending in bin then a .js file - extracting
+    // that pattern works regardless of what the package is scoped or renamed to.
+    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
+    if (where.status !== 0 || !where.stdout) return null;
+    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
+    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
+    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
+    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
+    if (!match) return null;
+    var candidate = path.join(path.dirname(cmdPath), match[1]);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch (e) {
+    return null;
+  }
+}
 
 function commandExists(cmd) {
   var probe = process.platform === 'win32'
@@ -17,22 +79,45 @@ function commandExists(cmd) {
   return probe.status === 0;
 }
 
+function runMemoryQuery(args) {
+  var entryPoint = resolveEmpiricalEntryPoint();
+  if (entryPoint) {
+    appendLog('resolved direct entry point: ' + entryPoint);
+    return spawnSync(process.execPath, [entryPoint].concat(args), {
+      encoding: 'utf8',
+      timeout: 10000,
+      shell: false
+    });
+  }
+
+  // Fallback: could not resolve a direct entry point (non-Windows, or resolution failed) — run
+  // the "empirical" command as before. On POSIX this is shell:false and safe. On Windows this is
+  // shell:true and CAN still mangle args as described above; it only triggers if the direct-entry
+  // resolution above failed, so degraded (not absent) results are the acceptable worst case here.
+  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
+  return spawnSync('empirical', args, {
+    encoding: 'utf8',
+    timeout: 10000,
+    shell: process.platform === 'win32'
+  });
+}
+
 function main() {
+  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
   if (!commandExists('empirical')) {
+    appendLog('empirical CLI not found on PATH, exiting');
     process.exit(0);
   }
 
-  var result = spawnSync('empirical', [
+  var result = runMemoryQuery([
     'memory', 'query',
     '--match', 'project context, conventions, recent decisions, user preferences',
     '--top-k', '8'
-  ], {
-    encoding: 'utf8',
-    timeout: 10000,
-    shell: process.platform === 'win32'
-  });
+  ]);
 
   if (!result || result.status !== 0 || !result.stdout) {
+    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
     process.exit(0);
   }
 
@@ -40,13 +125,17 @@ function main() {
   try {
     results = JSON.parse(result.stdout);
   } catch (e) {
+    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
     process.exit(0);
   }
 
   if (!Array.isArray(results) || results.length === 0) {
+    appendLog('memory query returned zero results');
     process.exit(0);
   }
 
+  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
+
   var lines = results.slice(0, 8).map(function (r) {
     var category = r && r.category ? r.category : 'memory';
     var summary = r && r.summary ? r.summary : '';
@@ -60,6 +149,204 @@ function main() {
 main();
 `;
 
+// EMPIRICAL_HOOK_STOP_SOURCE: fires once per assistant turn (Claude: Stop; Codex: Stop, turn-
+// scoped per codex-rs/hooks/src/engine/dispatcher.rs; Copilot: agentStop, "the main agent
+// finishes a turn" per GitHub's own hooks reference). This is the write-side counterpart to the
+// SessionStart hook above (which only covers recall, once per session boundary) - deliberately
+// simple: it does NOT parse the transcript to detect whether memory-worthy activity happened
+// this turn (transcript formats differ across all three platforms and getting that heuristic
+// wrong silently - the exact class of bug this session spent hours finding - is worse than an
+// unconditional reminder). It never calls the empirical CLI and makes no network call, so the
+// "wasteful per-turn hook" concern that killed the old per-turn UserPromptSubmit hook (see
+// installClaudeHooks below) does not apply here - this is a single static stdout write.
+// ALWAYS exits 0: per Claude Code's documented Stop hook contract, exit 2 forces the agent to
+// keep responding (a blocking decision) - a bug in a hook that's supposed to be an informational
+// nudge must never be able to trap a session in a forced-continuation loop, so this is
+// unconditional regardless of any error encountered.
+const EMPIRICAL_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  // Defensive loop guard: if a Stop hook's own forced-continuation output somehow triggers
+  // another Stop event before the agent produces new output, stop_hook_active (Claude's documented
+  // field name for this) prevents a reminder-print-loop. This hook never sets decision:block
+  // itself, but checking costs nothing and protects against any future change that does.
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  console.log('[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.');
+  process.exit(0);
+}
+
+main();
+`;
+
+// Claude-only variant of the Stop reminder above. Claude Code's Stop hook contract is the one
+// platform of the three we've actually confirmed supports safe forced-continuation: exit code 2
+// feeds stderr back to Claude as the reason and blocks the stop, and the stop_hook_active field on
+// the next invocation's stdin payload tells us a forced-continuation already happened for this
+// turn (Claude sets it specifically so a hook can avoid re-blocking and trapping the session in a
+// loop). EMPIRICAL_HOOK_STOP_SOURCE above already reads stop_hook_active defensively but never
+// blocks, so on Claude the reminder was silently logged and never reached the model - this variant
+// is the same script with the loop guard actually load-bearing: block once per turn, never twice.
+// Codex/Copilot keep using the silent EMPIRICAL_HOOK_STOP_SOURCE until their own Stop/agentStop
+// blocking semantics are confirmed against source the way Claude's was here.
+const CLAUDE_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  // stop_hook_active === true means Claude is re-invoking this hook because a PRIOR Stop hook
+  // (possibly this same one) already forced a continuation this turn. Blocking again here would
+  // trap the session in a forced-continuation loop, so this is the one case that must always exit
+  // 0 with no reminder, unconditionally.
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder (already blocked once this turn)');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + '), blocking once to surface reminder');
+
+  // Exit 2 is Claude Code's documented Stop-hook blocking signal: stderr is fed back to Claude as
+  // context and the turn is forced to continue instead of ending, which is what actually gets this
+  // reminder read (a plain stdout console.log + exit 0 is only logged, never seen by the model -
+  // this was this hook's exact original bug).
+  process.stderr.write('[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.\\n');
+  process.exit(2);
+}
+
+main();
+`;
+
+// UserPromptSubmit: fires before each turn is processed (Claude, Codex, and Copilot all support
+// this event under the same name per each platform's docs/source). This is the recall-side
+// counterpart to Stop's write-side reminder - deliberately a STATIC message, not a live
+// `empirical memory query` call: a prior per-turn hook in this codebase was removed for making an
+// unconditional network call on every single prompt (see the comment above installClaudeHooks),
+// and re-adding that cost here on three platforms at once was an explicit no per product decision.
+// The message itself is generated per-install from the actual plugin set being installed, not one
+// fixed string for everyone - e.g. someone who declined empirical-scar-tissue at install time
+// never sees a scar-tissue reminder, since that capability isn't actually available to them.
+function buildPromptReminderMessage(pluginNames) {
+  const names = normalizePluginNames(pluginNames);
+  const lines = [
+    'Before responding: if this task needs prior context (research, debugging, a spec or status update, a handoff), query Empirical memory first via the empirical-memory skill or empirical memory query - do not assume you already have enough context.'
+  ];
+  if (names.includes('empirical-work-history')) {
+    lines.push('If you are picking up previously completed work, check for a recent work-history entry before assuming there is none.');
+  }
+  if (names.includes('empirical-scar-tissue')) {
+    lines.push('Check for scar tissue before repeating a past mistake in this area.');
+  }
+  if (names.includes('empirical-todo')) {
+    lines.push('If there is an open todo for this project, check it before starting new work.');
+  }
+  return '[Empirical reminder] ' + lines.join(' ');
+}
+
+// Builds the full UserPromptSubmit hook script source with the tailored message baked in at
+// generation time (via JSON.stringify, so the message is embedded as a single already-escaped
+// string literal - substituted through `${}`, not written as raw template-literal source text,
+// which is what caused the earlier comment-escaping bug in this same file. Never do the latter).
+function buildUserPromptSubmitHookSource(pluginNames) {
+  const messageLiteral = JSON.stringify(buildPromptReminderMessage(pluginNames));
+  return `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'user-prompt-submit.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+appendLog('user-prompt-submit hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+console.log(${messageLiteral});
+process.exit(0);
+`;
+}
+
 function getEmpiricalHooksDir() {
   return path.join(os.homedir(), '.empirical', 'hooks');
 }
@@ -81,17 +368,21 @@ function removeEmpiricalHookEntries(entries, scriptPath) {
     .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
 }
 
-function installClaudeHooks() {
+function installClaudeHooks(pluginNames) {
   const hooksDir = getEmpiricalHooksDir();
   ensureDir(hooksDir);
 
-  // Older installs registered a per-turn UserPromptSubmit hook here too. That traded an
-  // unconditional network call on every single prompt for determinism, which is wasteful —
-  // the native empirical-memory plugin now covers ad-hoc reads/writes via
-  // Bash without that per-turn tax. SessionStart remains: one cheap call per session boundary.
+  // A prior version of this hook made an unconditional `empirical memory query` network call on
+  // every single prompt and was removed for being wasteful (see git history). This is a
+  // deliberate reintroduction at the SAME script path, but with fundamentally different content:
+  // a static, install-time-generated reminder with no network call at all - the cost concern that
+  // killed the old version does not apply to a plain stdout write.
   const userPromptScriptPath = path.join(hooksDir, 'claude-user-prompt-submit.js');
   const sessionStartScriptPath = path.join(hooksDir, 'claude-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'claude-stop.js');
   writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, CLAUDE_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
 
   const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
   const settings = readJsonIfExists(settingsPath) || {};
@@ -99,13 +390,10 @@ function installClaudeHooks() {
     settings.hooks = {};
   }
 
-  // Clean up the old per-turn hook entry if a prior install left one behind.
-  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
-    settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
-    if (settings.hooks.UserPromptSubmit.length === 0) {
-      delete settings.hooks.UserPromptSubmit;
-    }
-  }
+  settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command: buildHookCommand(userPromptScriptPath), timeout: 10 }]
+  });
 
   settings.hooks.SessionStart = removeEmpiricalHookEntries(settings.hooks.SessionStart, sessionStartScriptPath);
   for (const matcher of ['startup', 'resume', 'compact']) {
@@ -115,14 +403,148 @@ function installClaudeHooks() {
     });
   }
 
+  settings.hooks.Stop = removeEmpiricalHookEntries(settings.hooks.Stop, stopScriptPath);
+  settings.hooks.Stop.push({
+    hooks: [{ type: 'command', command: buildHookCommand(stopScriptPath), timeout: 10 }]
+  });
+
   writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
-  log('  - Claude SessionStart hook installed for deterministic memory lookups.');
+  log('  - Claude SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
+}
+
+// Codex CLI ships a real hooks system (confirmed against openai/codex source — codex-rs/hooks,
+// codex-rs/config/src/hook_config.rs — not assumed from docs alone, since third-party writeups
+// disagreed on Windows support). It reads <CODEX_HOME>/hooks.json (JSON, not the config.toml
+// used for MCP/model settings — a separate file, so this never touches config.toml) shaped as
+// { hooks: { SessionStart: [{ matcher, hooks: [{ type: 'command', command, commandWindows,
+// timeout }] }], ... } }. CODEX_HOME defaults to ~/.codex when unset, same convention as
+// ~/.claude for Claude Code.
+function getCodexHomeDir() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+
+function removeEmpiricalHooksJsonEntries(entries, scriptPath) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const filteredHooks = entry.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
+      );
+      return { ...entry, hooks: filteredHooks };
+    })
+    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
+}
+
+function installCodexHooks(pluginNames) {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  const sessionStartScriptPath = path.join(hooksDir, 'codex-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'codex-stop.js');
+  const userPromptScriptPath = path.join(hooksDir, 'codex-user-prompt-submit.js');
+  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, EMPIRICAL_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
+
+  const hooksJsonPath = path.join(getCodexHomeDir(), 'hooks.json');
+  const hooksFile = readJsonIfExists(hooksJsonPath) || {};
+  if (!hooksFile.hooks || typeof hooksFile.hooks !== 'object') {
+    hooksFile.hooks = {};
+  }
+
+  hooksFile.hooks.SessionStart = removeEmpiricalHooksJsonEntries(hooksFile.hooks.SessionStart, sessionStartScriptPath);
+  const sessionStartCommand = buildHookCommand(sessionStartScriptPath);
+  for (const matcher of ['startup', 'resume']) {
+    hooksFile.hooks.SessionStart.push({
+      matcher,
+      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommand, timeout: 15 }]
+    });
+  }
+
+  hooksFile.hooks.Stop = removeEmpiricalHooksJsonEntries(hooksFile.hooks.Stop, stopScriptPath);
+  const stopCommand = buildHookCommand(stopScriptPath);
+  hooksFile.hooks.Stop.push({
+    hooks: [{ type: 'command', command: stopCommand, commandWindows: stopCommand, timeout: 10 }]
+  });
+
+  // Confirmed against codex-rs/config/src/hook_config.rs's HookEventsToml serde renames: the
+  // config-file key is PascalCase "UserPromptSubmit", same casing convention as SessionStart/Stop.
+  hooksFile.hooks.UserPromptSubmit = removeEmpiricalHooksJsonEntries(hooksFile.hooks.UserPromptSubmit, userPromptScriptPath);
+  const userPromptCommand = buildHookCommand(userPromptScriptPath);
+  hooksFile.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command: userPromptCommand, commandWindows: userPromptCommand, timeout: 10 }]
+  });
+
+  writeFile(hooksJsonPath, `${JSON.stringify(hooksFile, null, 2)}\n`);
+  log('  - Codex SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
+}
+
+// GitHub Copilot CLI's hook config is one JSON file per hook under ~/.copilot/hooks/ (any
+// filename — confirmed via GitHub's own docs at docs.github.com/en/copilot/reference/hooks-
+// reference), so unlike Claude/Codex this never needs to merge into a shared file: Empirical
+// owns this file outright and can just overwrite it. Event key for turn-end is "agentStop"
+// ("the main agent finishes a turn" per the same docs) — not "stop"/"Stop" like Claude/Codex.
+// Schema: { version: 1, hooks: { sessionStart: [...], agentStop: [...] } }.
+function installCopilotHooks(pluginNames) {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  const sessionStartScriptPath = path.join(hooksDir, 'copilot-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'copilot-stop.js');
+  const userPromptScriptPath = path.join(hooksDir, 'copilot-user-prompt-submit.js');
+  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, EMPIRICAL_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
+
+  const copilotHooksDir = path.join(os.homedir(), '.copilot', 'hooks');
+  ensureDir(copilotHooksDir);
+
+  // Prior versions of this installer wrote a single-purpose "empirical-session-start.json" —
+  // remove it now that both events live in one unified file, so a stale duplicate registration
+  // never lingers alongside the new one.
+  const legacyHookFilePath = path.join(copilotHooksDir, 'empirical-session-start.json');
+  try {
+    const fs = require('fs');
+    if (fs.existsSync(legacyHookFilePath)) fs.unlinkSync(legacyHookFilePath);
+  } catch (_error) {
+    // best-effort cleanup only
+  }
+
+  const hookFilePath = path.join(copilotHooksDir, 'empirical-hooks.json');
+  const hookFileContent = {
+    version: 1,
+    hooks: {
+      sessionStart: [
+        { type: 'command', command: buildHookCommand(sessionStartScriptPath), timeoutSec: 15 }
+      ],
+      // "userPromptSubmitted" per GitHub's hooks reference ("The user submits a prompt") - not
+      // "userPromptSubmit" (that camelCase spelling is Claude/Codex's convention, not Copilot's).
+      userPromptSubmitted: [
+        { type: 'command', command: buildHookCommand(userPromptScriptPath), timeoutSec: 10 }
+      ],
+      agentStop: [
+        { type: 'command', command: buildHookCommand(stopScriptPath), timeoutSec: 10 }
+      ]
+    }
+  };
+
+  writeFile(hookFilePath, `${JSON.stringify(hookFileContent, null, 2)}\n`);
+  log('  - Copilot SessionStart + userPromptSubmitted + agentStop hooks installed for deterministic memory lookups and reminders.');
 }
 
 module.exports = {
   CLAUDE_HOOK_SESSION_START_SOURCE,
+  EMPIRICAL_HOOK_STOP_SOURCE,
+  CLAUDE_HOOK_STOP_SOURCE,
+  buildPromptReminderMessage,
+  buildUserPromptSubmitHookSource,
   getEmpiricalHooksDir,
   buildHookCommand,
   removeEmpiricalHookEntries,
-  installClaudeHooks
+  installClaudeHooks,
+  getCodexHomeDir,
+  removeEmpiricalHooksJsonEntries,
+  installCodexHooks,
+  installCopilotHooks
 };

package/lib/installers/promptBlocks.js

@@ -159,16 +159,28 @@ function buildEmpiricalSkillFrontmatter(options = {}) {
     name: 'empirical-memory',
     // Keep frontmatter deliberately simple: Copilot's YAML parser rejects an
     // unquoted colon in a plain scalar, and does not support when_to_use.
-    description: 'Use Empirical CLI and MCP to recall and save durable project context across sessions and projects.'
+    // Covers both triggers this skill owns: durable project memory recall/save,
+    // and "how do I use Empirical" questions (CLI commands, install, auth,
+    // workspaces, kits, skills) - a single skill so there's no ambiguity about
+    // which one to check for an Empirical-shaped question.
+    description: 'Use Empirical to recall/save durable project context across sessions, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.'
   };
 }
 
 function buildEmpiricalSkillBody(options = {}) {
   const policyLines = buildSharedEmpiricalPolicyLines(options);
   const workflows = workflowLabelsSummary(options);
-  return `## Empirical Memory - Use It Like grep/view
+  return `## Empirical - Use It Like grep/view
 
-Use this skill for ${workflows}, whenever prior context may matter, and whenever the user asks to remember, recall, update, or forget information.
+This skill covers two distinct triggers. Check both, not just the first one that seems to fit:
+
+1. **Durable memory recall/save** - for ${workflows}, whenever prior context may matter, and
+   whenever the user asks to remember, recall, update, or forget information.
+2. **"How do I use Empirical" questions** - CLI command syntax, install/auth/workspace/kit/skill
+   setup, or any question about what Empirical can do or how it's configured. Don't answer these
+   from general knowledge or by grepping the empirical_v2 source - run \`empirical doc\` (lists
+   topics) or \`empirical doc <topic>\` via the available shell for the current, agent-readable
+   answer before guessing.
 
 Prefer calling the \`empirical\` CLI directly via the available shell over the MCP tools when both are
 available: \`empirical memory query|get|list|record|note|update|delete\`. The CLI doesn't require an

package/lib/workspaceCommands.js

@@ -6,8 +6,8 @@ const { getEnv, parseFlag, parseOption } = require('./env');
 const { ensureHeadlessToken, resolveAccessToken, buildApiAuthHeaders } = require('./auth');
 const { readStoredOAuthClient } = require('./oauthClient');
 const { deriveBaseUrlFromMcpUrl } = require('./constants');
-const { withCliAnalyticsContext } = require('./memoryCommands');
-const { readSelectedWorkspace, writeSelectedWorkspace, clearSelectedWorkspace } = require('./workspaceContext');
+const { withCliAnalyticsContext } = require('./memoryCommands');
+const { readSelectedWorkspace, writeSelectedWorkspace, clearSelectedWorkspace } = require('./workspaceContext');
 
 function isWorkspaceCommand(args) {
   if (args[0] !== 'workspace') return false;
@@ -43,7 +43,7 @@ function targetFromOption(option, teamBrain) {
   return {
     ...(option || {}),
     key: option?.key || teamBrain?.workspaceId,
-    selectionKey: option?.key || teamBrain?.workspaceId || option?.workspaceId,
+    selectionKey: option?.key || teamBrain?.workspaceId || option?.workspaceId,
     label: option?.label || teamBrain?.name,
     isDefault: Boolean(option?.isDefault),
     workspaceId: teamBrain?.workspaceId || option?.workspaceId || null,
@@ -118,12 +118,20 @@ async function getWorkspaceCommandAuth() {
   if (!accessToken) {
     throw new Error('No access token available. Run `empirical oauth bootstrap headless --prompt-credentials` first.');
   }
-  const clientId = tokenPayload?.clientId || getEnv('EMPIRICAL_CLIENT_ID') || readStoredOAuthClient()?.clientId;
+  // clientId is genuinely optional here now -- `list`/`current` fall back to a per-user endpoint
+  // (GET /api/v1/users/me/workspaces) when it's absent, since most CLI usage is a plain API key
+  // with no OAuth client_credentials flow at all (see `doctor`'s token_type check). Actions that
+  // mutate a client's workspace selection (select/use/create/delete/invite) still require one --
+  // there's no per-user equivalent of "which workspace is this client currently using."
+  const clientId = tokenPayload?.clientId || getEnv('EMPIRICAL_CLIENT_ID') || readStoredOAuthClient()?.clientId || null;
+  const baseUrl = getEnv('EMPIRICAL_BASE_URL', deriveBaseUrlFromMcpUrl() || 'https://empirical.gauzza.com');
+  return { baseUrl, clientId, accessToken };
+}
+
+function requireClientId(clientId) {
   if (!clientId) {
     throw new Error('No OAuth client ID found. Run `empirical oauth client set --client-id <id>` first.');
   }
-  const baseUrl = getEnv('EMPIRICAL_BASE_URL', deriveBaseUrlFromMcpUrl() || 'https://empirical.gauzza.com');
-  return { baseUrl, clientId, accessToken };
 }
 
 async function runWorkspaceCommand(args) {
@@ -132,9 +140,13 @@ async function runWorkspaceCommand(args) {
     async () => {
       const action = args[1];
       const { baseUrl, clientId, accessToken } = await getWorkspaceCommandAuth();
-      const encodedClientId = encodeURIComponent(clientId);
-      const listUrl = new URL(`/oauth/clients/${encodedClientId}/workspaces`, baseUrl).toString();
-      const currentUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
+      const encodedClientId = clientId ? encodeURIComponent(clientId) : null;
+      const listUrl = clientId
+        ? new URL(`/oauth/clients/${encodedClientId}/workspaces`, baseUrl).toString()
+        : new URL('/api/v1/users/me/workspaces', baseUrl).toString();
+      const currentUrl = clientId
+        ? new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString()
+        : null; // no per-client selection endpoint to hit -- 'current' derives it from listUrl's `selected` flags instead
       const teamBrainsUrl = new URL('/api/v1/team-brains', baseUrl).toString();
       const authHeaders = buildApiAuthHeaders(accessToken);
 
@@ -151,13 +163,21 @@ async function runWorkspaceCommand(args) {
         return;
       }
 
-      if (action === 'current') {
-        const locallySelected = readSelectedWorkspace();
-        if (locallySelected) {
-          log(`Current workspace: ${locallySelected.label || locallySelected.workspaceId}`);
-          return;
-        }
-        const payload = await httpJson(currentUrl, 'GET', null, authHeaders);
+      if (action === 'current') {
+        const locallySelected = readSelectedWorkspace();
+        if (locallySelected) {
+          log(`Current workspace: ${locallySelected.label || locallySelected.workspaceId}`);
+          return;
+        }
+        if (!clientId) {
+          const payload = await httpJson(listUrl, 'GET', null, authHeaders);
+          const selected = payload.defaultOption.selected
+            ? payload.defaultOption
+            : (payload.workspaces || []).find((ws) => ws.selected) || payload.defaultOption;
+          log(`Current workspace: ${selected.label || 'Default Brain'}`);
+          return;
+        }
+        const payload = await httpJson(currentUrl, 'GET', null, authHeaders);
         log(`Current workspace: ${payload?.current?.label || 'Default Brain'}`);
         if (payload?.locked) {
           log('This OAuth client is admin-locked to a workspace.');
@@ -166,6 +186,7 @@ async function runWorkspaceCommand(args) {
       }
 
       if (action === 'select' || action === 'use') {
+        requireClientId(clientId);
         const [payload, teamPayload] = await Promise.all([
           httpJson(listUrl, 'GET', null, authHeaders),
           httpJson(teamBrainsUrl, 'GET', null, authHeaders),
@@ -193,13 +214,13 @@ async function runWorkspaceCommand(args) {
         if (!target?.selectionKey) throw new Error(`Workspace not found: ${requested}`);
 
         const updateUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
-        const updated = await httpJson(updateUrl, 'POST', { key: target.selectionKey }, authHeaders);
-        if (target.isDefault) {
-          clearSelectedWorkspace();
-        } else if (target.workspaceId) {
-          writeSelectedWorkspace({ workspaceId: target.workspaceId, key: target.key, label: target.label });
-        }
-        log(uiSuccess(`Workspace selected: ${updated?.current?.label || target.label || target.selectionKey}`));
+        const updated = await httpJson(updateUrl, 'POST', { key: target.selectionKey }, authHeaders);
+        if (target.isDefault) {
+          clearSelectedWorkspace();
+        } else if (target.workspaceId) {
+          writeSelectedWorkspace({ workspaceId: target.workspaceId, key: target.key, label: target.label });
+        }
+        log(uiSuccess(`Workspace selected: ${updated?.current?.label || target.label || target.selectionKey}`));
         return;
       }
 
@@ -241,18 +262,20 @@ async function runWorkspaceCommand(args) {
 
         log(`Soft-deleting workspace ${targetDescription}...`);
         await httpJson(new URL(`/api/v1/team-brains/${encodeURIComponent(target.workspaceId)}`, baseUrl).toString(), 'DELETE', null, authHeaders);
-        if (target.selected) {
+        if (target.selected && clientId) {
           const updateUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
           const updated = await httpJson(updateUrl, 'POST', { key: 'default_brain' }, authHeaders);
-          log(uiSuccess(`Soft-deleted workspace ${targetDescription}. Active workspace reset to ${updated?.current?.label || 'Default Brain'}.`));
-          clearSelectedWorkspace();
-        } else {
+          log(uiSuccess(`Soft-deleted workspace ${targetDescription}. Active workspace reset to ${updated?.current?.label || 'Default Brain'}.`));
+          clearSelectedWorkspace();
+        } else {
           log(uiSuccess(`Soft-deleted workspace ${targetDescription}.`));
+          clearSelectedWorkspace();
         }
         return;
       }
 
       if (action === 'invite') {
+        requireClientId(clientId);
         const inviteAction = args[2];
         const currentPayload = await httpJson(currentUrl, 'GET', null, authHeaders);
         const current = currentPayload?.current;

package/package.json

@@ -1,14 +1,9 @@
 {
-  "name": "@empirical-gauzza/cli",
-  "version": "1.0.9",
+  "name": "@empirical-gauzza/cli",
+  "version": "1.0.11",
   "description": "Empirical CLI installer and local MCP wiring helper",
   "type": "commonjs",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mattgauzza/empirical.git",
-    "directory": "packages/cli"
-  },
   "homepage": "https://empirical.gauzza.com/docs/cli-details",
   "publishConfig": {
     "access": "public"