@empirical-gauzza/cli 1.0.19 → 1.0.20

package/lib/installWizard.js

@@ -24,6 +24,7 @@ const { installClaudeHooks, installCodexHooks, installCopilotHooks } = require('
 const { runCodex } = require('./installers/codex');
 const { installNativePlugin, OPTIONAL_PLUGIN_NAMES } = require('./installers/nativePlugin');
 const { policyFromInstallerOptions, savePolicy: persistPolicy } = require('./policyCommands');
+const { writeIntegrationMode } = require('./deviceConfig');
 
 function pluginNamesForInstallerOptions(options = {}) {
   const names = ['empirical-memory'];
@@ -74,6 +75,10 @@ async function runInstallFlow() {
     log('');
   }
 
+  // C-001: persist the chosen mode so later, unattended Skill refreshes (a plugin auto-update or
+  // a `kit sync`/`kit use` run) still pick the mode the user actually chose here, not a default.
+  writeIntegrationMode(integrationMode);
+
   let promptOptions;
   let savePolicyEnabled;
 
@@ -231,7 +236,7 @@ async function runInstallFlow() {
       if (integrationMode === 2) {
         // CLI-direct: skip MCP registration; the native plugin owns guidance.
         const pluginNames = pluginNamesForInstallerOptions(promptOptions);
-        installNativePlugin(target.id, pluginNames);
+        installNativePlugin(target.id, pluginNames, integrationMode);
         log(`  - ${target.label} native plugins installed: ${pluginNames.join(', ')}.`);
         if (target.id === 'claude') {
           try {
@@ -260,7 +265,8 @@ async function runInstallFlow() {
         const pluginNames = pluginNamesForInstallerOptions(promptOptions);
         const installResult = target.install(headlessToken, promptOptions, {
           writeGlobalInstructions: false,
-          pluginNames
+          pluginNames,
+          integrationMode
         });
         log(uiSuccess(`Done: ${target.label}`));
         if (target.id === 'codex') {

package/lib/installers/claude.js

@@ -1,93 +1,110 @@
-'use strict';
-
-const { log, warn } = require('../ui');
-const { commandExists, runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
-const { readStoredOAuthClient } = require('../oauthClient');
-const {
-  EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL
-} = require('../constants');
-const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
-const { installClaudeHooks } = require('./hooks');
-const { installNativePlugin } = require('./nativePlugin');
-
-function runClaude(args, options = {}) {
-  return runResolvedCommand('claude', args, options);
-}
-
-function isClaudeServerConfigured(name) {
-  const result = runClaude(['mcp', 'get', name], { stdio: 'ignore' });
-  return result.status === 0;
-}
-
-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(installOptions.pluginNames);
-  } catch (error) {
-    warn(`  - Could not install Claude hooks for deterministic memory lookups: ${error.message}`);
-  }
-
-  if (!commandExists('claude')) {
-    warn('  - Claude CLI not found on PATH. Skipped Claude MCP registration.');
-    return;
-  }
-
-  const storedClient = readStoredOAuthClient();
-
-  // Keep the server definition deterministic across canonical and legacy names.
-  for (const serverName of [EMPIRICAL_MCP_NAME, ...EMPIRICAL_MCP_LEGACY_NAMES]) {
-    runClaude(['mcp', 'remove', serverName], { stdio: 'ignore' });
-    runClaude(['mcp', 'remove', serverName, '-s', 'user'], { stdio: 'ignore' });
-    runClaude(['mcp', 'remove', serverName, '-s', 'local'], { stdio: 'ignore' });
-    runClaude(['mcp', 'remove', serverName, '-s', 'project'], { stdio: 'ignore' });
-  }
-
-  let lastFailureSummary = '';
-  for (let attempt = 1; attempt <= 2; attempt += 1) {
-    if (attempt > 1) {
-      log('  - Retrying Claude MCP registration...');
-    }
-
-    const addArgs = [
-      'mcp',
-      'add',
-      '--scope',
-      'user',
-      '--transport',
-      'http',
-      EMPIRICAL_MCP_NAME,
-      EMPIRICAL_MCP_URL
-    ];
-    if (storedClient?.clientId) {
-      addArgs.push('--client-id', storedClient.clientId);
-    }
-
-    const addResult = runClaude(addArgs, { stdio: attempt === 1 ? 'inherit' : 'pipe' });
-    if (addResult.status === 0) {
-      return;
-    }
-    lastFailureSummary = summarizeProcessOutput(addResult);
-
-    if (isClaudeServerConfigured(EMPIRICAL_MCP_NAME)) {
-      warn('  - Claude returned a non-zero status, but MCP server is present. Continuing.');
-      return;
-    }
-  }
-
-  const detail = lastFailureSummary ? ` Details: ${lastFailureSummary}` : '';
-  throw new Error(`claude mcp add failed after retry.${detail}`);
-}
-
-module.exports = {
-  runClaude,
-  isClaudeServerConfigured,
-  installClaude
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log, warn } = require('../ui');
+const { commandExists, runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
+const { readStoredOAuthClient } = require('../oauthClient');
+const {
+  EMPIRICAL_MCP_NAME, EMPIRICAL_MCP_LEGACY_NAMES, EMPIRICAL_MCP_URL
+} = require('../constants');
+const { INSTALL_PROMPT_OPTIONS_DEFAULTS } = require('./promptBlocks');
+const { installClaudeHooks } = require('./hooks');
+const { installNativePlugin, CORE_PLUGIN_NAME } = require('./nativePlugin');
+const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+
+function runClaude(args, options = {}) {
+  return runResolvedCommand('claude', args, options);
+}
+
+function isClaudeServerConfigured(name) {
+  const result = runClaude(['mcp', 'get', name], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function installClaude(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
+  // 2026-08-24: previously left CLAUDE.md untouched, trusting hooks + the installable skill
+  // alone. That trust proved false in a real session (see project memory "agent behavior" scar
+  // tissue) -- an agent's own built-in memory feature, framed in first-person identity language
+  // in its system prompt, out-competed the skill despite reminder hooks firing every turn. This
+  // writes the same kind of identity-framed statement into the one file Claude reads every
+  // session unconditionally, inside a clearly delimited block so any of the user's own content
+  // in CLAUDE.md is left untouched.
+  try {
+    const claudeMdPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
+    upsertCoreMemoryBlock(claudeMdPath, block);
+    log(`  - Wrote Empirical core memory guidance to ${claudeMdPath}.`);
+  } catch (error) {
+    warn(`  - Could not write Empirical core memory guidance to CLAUDE.md: ${error.message}`);
+  }
+
+  // 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, installOptions.integrationMode);
+  log(`  - Claude native plugins installed: ${(installOptions.pluginNames || ['empirical-memory']).join(', ')}.`);
+
+  try {
+    installClaudeHooks(installOptions.pluginNames);
+  } catch (error) {
+    warn(`  - Could not install Claude hooks for deterministic memory lookups: ${error.message}`);
+  }
+
+  if (!commandExists('claude')) {
+    warn('  - Claude CLI not found on PATH. Skipped Claude MCP registration.');
+    return;
+  }
+
+  const storedClient = readStoredOAuthClient();
+
+  // Keep the server definition deterministic across canonical and legacy names.
+  for (const serverName of [EMPIRICAL_MCP_NAME, ...EMPIRICAL_MCP_LEGACY_NAMES]) {
+    runClaude(['mcp', 'remove', serverName], { stdio: 'ignore' });
+    runClaude(['mcp', 'remove', serverName, '-s', 'user'], { stdio: 'ignore' });
+    runClaude(['mcp', 'remove', serverName, '-s', 'local'], { stdio: 'ignore' });
+    runClaude(['mcp', 'remove', serverName, '-s', 'project'], { stdio: 'ignore' });
+  }
+
+  let lastFailureSummary = '';
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    if (attempt > 1) {
+      log('  - Retrying Claude MCP registration...');
+    }
+
+    const addArgs = [
+      'mcp',
+      'add',
+      '--scope',
+      'user',
+      '--transport',
+      'http',
+      EMPIRICAL_MCP_NAME,
+      EMPIRICAL_MCP_URL
+    ];
+    if (storedClient?.clientId) {
+      addArgs.push('--client-id', storedClient.clientId);
+    }
+
+    const addResult = runClaude(addArgs, { stdio: attempt === 1 ? 'inherit' : 'pipe' });
+    if (addResult.status === 0) {
+      return;
+    }
+    lastFailureSummary = summarizeProcessOutput(addResult);
+
+    if (isClaudeServerConfigured(EMPIRICAL_MCP_NAME)) {
+      warn('  - Claude returned a non-zero status, but MCP server is present. Continuing.');
+      return;
+    }
+  }
+
+  const detail = lastFailureSummary ? ` Details: ${lastFailureSummary}` : '';
+  throw new Error(`claude mcp add failed after retry.${detail}`);
+}
+
+module.exports = {
+  runClaude,
+  isClaudeServerConfigured,
+  installClaude
+};

package/lib/installers/codex.js

@@ -1,88 +1,101 @@
-'use strict';
-
-const { log, warn } = require('../ui');
-const { commandExists, runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
-const { persistAccessToken } = require('../oauthClient');
-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 = {}) {
-  return runResolvedCommand('codex', args, options);
-}
-
-function isCodexServerConfigured(name) {
-  const result = runCodex(['mcp', 'get', name], { stdio: 'ignore' });
-  return result.status === 0;
-}
-
-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;
-  }
-
-  for (const serverName of [EMPIRICAL_MCP_NAME, ...EMPIRICAL_MCP_LEGACY_NAMES]) {
-    if (isCodexServerConfigured(serverName)) {
-      runCodex(['mcp', 'remove', serverName], { stdio: 'ignore' });
-    }
-  }
-
-  const addArgs = ['mcp', 'add', EMPIRICAL_MCP_NAME, '--url', EMPIRICAL_MCP_URL];
-  const permanentToken = headlessToken?.apiKey || '';
-  if (permanentToken) {
-    persistAccessToken(permanentToken);
-    addArgs.push('--bearer-token-env-var', 'EMPIRICAL_ACCESS_TOKEN');
-    log('  - Registering Codex MCP server with permanent environment-backed authentication...');
-  } else {
-    log('  - Registering Codex MCP server (OAuth flow may open in browser)...');
-  }
-
-  let lastFailureSummary = '';
-  for (let attempt = 1; attempt <= 2; attempt += 1) {
-    if (attempt > 1) {
-      log('  - Retrying Codex MCP registration...');
-    }
-
-    const addResult = runCodex(
-      addArgs,
-      { stdio: attempt === 1 ? 'inherit' : 'pipe' }
-    );
-    if (addResult.status === 0) {
-      return { needsPostLogin: false };
-    }
-    lastFailureSummary = summarizeProcessOutput(addResult);
-
-    // Codex OAuth flow can return non-zero even when the server is persisted.
-    if (isCodexServerConfigured(EMPIRICAL_MCP_NAME)) {
-      warn('  - Codex returned a non-zero status, but MCP server is present. Continuing.');
-      return { needsPostLogin: true };
-    }
-  }
-
-  const detail = lastFailureSummary ? ` Details: ${lastFailureSummary}` : '';
-  throw new Error(`codex mcp add failed after retry.${detail}`);
-}
-
-module.exports = {
-  runCodex,
-  isCodexServerConfigured,
-  installCodex
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log, warn } = require('../ui');
+const { commandExists, runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
+const { persistAccessToken } = require('../oauthClient');
+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, CORE_PLUGIN_NAME } = require('./nativePlugin');
+const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+
+function runCodex(args, options = {}) {
+  return runResolvedCommand('codex', args, options);
+}
+
+function isCodexServerConfigured(name) {
+  const result = runCodex(['mcp', 'get', name], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function installCodex(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
+  // 2026-08-24: see claude.js's identical block for why this now writes AGENTS.md instead of
+  // leaving it untouched -- hooks + an installable skill alone were not enough against a
+  // competing identity-framed built-in memory feature in a real session.
+  try {
+    const agentsMdPath = path.join(os.homedir(), '.codex', 'AGENTS.md');
+    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
+    upsertCoreMemoryBlock(agentsMdPath, block);
+    log(`  - Wrote Empirical core memory guidance to ${agentsMdPath}.`);
+  } catch (error) {
+    warn(`  - Could not write Empirical core memory guidance to AGENTS.md: ${error.message}`);
+  }
+
+  // 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, installOptions.integrationMode);
+  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;
+  }
+
+  for (const serverName of [EMPIRICAL_MCP_NAME, ...EMPIRICAL_MCP_LEGACY_NAMES]) {
+    if (isCodexServerConfigured(serverName)) {
+      runCodex(['mcp', 'remove', serverName], { stdio: 'ignore' });
+    }
+  }
+
+  const addArgs = ['mcp', 'add', EMPIRICAL_MCP_NAME, '--url', EMPIRICAL_MCP_URL];
+  const permanentToken = headlessToken?.apiKey || '';
+  if (permanentToken) {
+    persistAccessToken(permanentToken);
+    addArgs.push('--bearer-token-env-var', 'EMPIRICAL_ACCESS_TOKEN');
+    log('  - Registering Codex MCP server with permanent environment-backed authentication...');
+  } else {
+    log('  - Registering Codex MCP server (OAuth flow may open in browser)...');
+  }
+
+  let lastFailureSummary = '';
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    if (attempt > 1) {
+      log('  - Retrying Codex MCP registration...');
+    }
+
+    const addResult = runCodex(
+      addArgs,
+      { stdio: attempt === 1 ? 'inherit' : 'pipe' }
+    );
+    if (addResult.status === 0) {
+      return { needsPostLogin: false };
+    }
+    lastFailureSummary = summarizeProcessOutput(addResult);
+
+    // Codex OAuth flow can return non-zero even when the server is persisted.
+    if (isCodexServerConfigured(EMPIRICAL_MCP_NAME)) {
+      warn('  - Codex returned a non-zero status, but MCP server is present. Continuing.');
+      return { needsPostLogin: true };
+    }
+  }
+
+  const detail = lastFailureSummary ? ` Details: ${lastFailureSummary}` : '';
+  throw new Error(`codex mcp add failed after retry.${detail}`);
+}
+
+module.exports = {
+  runCodex,
+  isCodexServerConfigured,
+  installCodex
+};

package/lib/installers/copilot.js

@@ -1,87 +1,97 @@
-'use strict';
-
-const os = require('os');
-const path = require('path');
-const { log, warn } = require('../ui');
-const { ensureDir, readJsonIfExists, readUtf8IfExists, writeFile } = require('../fsUtils');
-const { getEnv } = require('../env');
-const { readStoredOAuthClient, getLocalOAuthClientPath } = require('../oauthClient');
-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 = {}) {
-  const home = os.homedir();
-  const copilotDir = path.join(home, '.copilot');
-  const mcpConfigPath = path.join(copilotDir, 'mcp-config.json');
-  const instructionsPath = path.join(copilotDir, 'copilot-instructions.md');
-
-  ensureDir(copilotDir);
-
-  const mcpConfig = readJsonIfExists(mcpConfigPath) || {};
-  if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== 'object') {
-    mcpConfig.mcpServers = {};
-  }
-
-  for (const legacyName of EMPIRICAL_MCP_LEGACY_NAMES) {
-    if (legacyName && legacyName in mcpConfig.mcpServers) {
-      delete mcpConfig.mcpServers[legacyName];
-    }
-  }
-
-  const storedClient = readStoredOAuthClient();
-  const oauthClientId = getEnv(
-    'EMPIRICAL_COPILOT_OAUTH_CLIENT_ID',
-    storedClient?.clientId || COPILOT_OAUTH_CLIENT_ID
-  );
-  const oauthClientSecret = getEnv(
-    'EMPIRICAL_COPILOT_OAUTH_CLIENT_SECRET',
-    storedClient?.clientSecret || ''
-  );
-
-  mcpConfig.mcpServers[EMPIRICAL_MCP_NAME] = {
-    oauthPublicClient: !oauthClientSecret,
-    type: 'http',
-    tools: ['*'],
-    url: EMPIRICAL_MCP_URL,
-    oauthClientId
-  };
-  if (oauthClientSecret) {
-    mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].oauthClientSecret = oauthClientSecret;
-  } else if ('oauthClientSecret' in mcpConfig.mcpServers[EMPIRICAL_MCP_NAME]) {
-    delete mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].oauthClientSecret;
-  }
-
-  if ('httpHeaders' in mcpConfig.mcpServers[EMPIRICAL_MCP_NAME]) {
-    delete mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].httpHeaders;
-  }
-
-  writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`);
-
-  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()}.`);
-  }
-  log('  - Copilot OAuth is typically completed on first MCP use (no standalone `copilot mcp login` command).');
-}
-
-module.exports = {
-  installCopilot
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log, warn } = require('../ui');
+const { ensureDir, readJsonIfExists, readUtf8IfExists, writeFile } = require('../fsUtils');
+const { getEnv } = require('../env');
+const { readStoredOAuthClient, getLocalOAuthClientPath } = require('../oauthClient');
+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, CORE_PLUGIN_NAME } = require('./nativePlugin');
+const { buildCoreMemoryBlock, upsertCoreMemoryBlock } = require('./coreMemoryBlock');
+
+function installCopilot(headlessToken, promptOptions = INSTALL_PROMPT_OPTIONS_DEFAULTS, installOptions = {}) {
+  const home = os.homedir();
+  const copilotDir = path.join(home, '.copilot');
+  const mcpConfigPath = path.join(copilotDir, 'mcp-config.json');
+  const instructionsPath = path.join(copilotDir, 'copilot-instructions.md');
+
+  ensureDir(copilotDir);
+
+  const mcpConfig = readJsonIfExists(mcpConfigPath) || {};
+  if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== 'object') {
+    mcpConfig.mcpServers = {};
+  }
+
+  for (const legacyName of EMPIRICAL_MCP_LEGACY_NAMES) {
+    if (legacyName && legacyName in mcpConfig.mcpServers) {
+      delete mcpConfig.mcpServers[legacyName];
+    }
+  }
+
+  const storedClient = readStoredOAuthClient();
+  const oauthClientId = getEnv(
+    'EMPIRICAL_COPILOT_OAUTH_CLIENT_ID',
+    storedClient?.clientId || COPILOT_OAUTH_CLIENT_ID
+  );
+  const oauthClientSecret = getEnv(
+    'EMPIRICAL_COPILOT_OAUTH_CLIENT_SECRET',
+    storedClient?.clientSecret || ''
+  );
+
+  mcpConfig.mcpServers[EMPIRICAL_MCP_NAME] = {
+    oauthPublicClient: !oauthClientSecret,
+    type: 'http',
+    tools: ['*'],
+    url: EMPIRICAL_MCP_URL,
+    oauthClientId
+  };
+  if (oauthClientSecret) {
+    mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].oauthClientSecret = oauthClientSecret;
+  } else if ('oauthClientSecret' in mcpConfig.mcpServers[EMPIRICAL_MCP_NAME]) {
+    delete mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].oauthClientSecret;
+  }
+
+  if ('httpHeaders' in mcpConfig.mcpServers[EMPIRICAL_MCP_NAME]) {
+    delete mcpConfig.mcpServers[EMPIRICAL_MCP_NAME].httpHeaders;
+  }
+
+  writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`);
+
+  // 2026-08-24: see claude.js's identical block for why this now writes copilot-instructions.md
+  // instead of leaving it untouched -- hooks + an installable skill alone were not enough
+  // against a competing identity-framed built-in memory feature in a real session.
+  try {
+    const block = buildCoreMemoryBlock({ pluginNames: installOptions.pluginNames || [CORE_PLUGIN_NAME] });
+    upsertCoreMemoryBlock(instructionsPath, block);
+    log(`  - Wrote Empirical core memory guidance to ${instructionsPath}.`);
+  } catch (error) {
+    warn(`  - Could not write Empirical core memory guidance to copilot-instructions.md: ${error.message}`);
+  }
+
+  // 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, installOptions.integrationMode);
+  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()}.`);
+  }
+  log('  - Copilot OAuth is typically completed on first MCP use (no standalone `copilot mcp login` command).');
+}
+
+module.exports = {
+  installCopilot
+};