docs(codex): clarify explicit MCP pin refresh and verify shared recommendation

README.md

@@ -1515,9 +1515,14 @@ npm install && bash scripts/sync-ecc-to-codex.sh
 cp .codex/config.toml ~/.codex/config.toml
 ```
 
-The sync script safely merges ECC MCP servers into your existing `~/.codex/config.toml` using an **add-only** strategy: it never removes or modifies your existing servers. Run with `--dry-run` to preview changes, or `--update-mcp` to force-refresh ECC servers to the latest recommended config.
+Normal MCP sync preserves existing server settings and warns when they differ from ECC's recommendation. An existing `chrome-devtools-mcp@latest` entry therefore stays unchanged; updating the repository alone does not adopt the recommended `chrome-devtools-mcp@1.10.1` pin. Existing legacy-sync users can preview and explicitly apply the refresh from the updated ECC checkout:
 
-For Context7, ECC uses the canonical Codex section name `[mcp_servers.context7]` while still launching the `@upstash/context7-mcp` package. If you already have a legacy `[mcp_servers.context7-mcp]` entry, `--update-mcp` migrates it to the canonical section name.
+```bash
+bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp
+bash scripts/sync-ecc-to-codex.sh --update-mcp
+```
+
+Review the preview before applying: `--update-mcp` replaces the entire recommended `chrome-devtools` server section, including custom command arguments and nested settings. Unrelated user-managed servers remain in place. Retired defaults such as Context7 are not refreshed or migrated by this flag.
 
 Codex macOS app:
 - Open this repository as your workspace.
@@ -1533,7 +1538,7 @@ Codex macOS app:
 | Config | 1 | `.codex/config.toml`: top-level approvals/sandbox/web_search, MCP servers, notifications, profiles |
 | AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) |
 | Skills | 32 | `.agents/skills/`: SKILL.md + agents/openai.yaml per skill |
-| MCP Servers | 6 | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking (7 with Supabase via `--update-mcp` sync) |
+| MCP Servers | 6 legacy reference entries | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking. Current managed sync recommends `chrome-devtools`; see the explicit refresh instructions above. |
 | Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) |
 | Agent Roles | 3 | `.codex/agents/`: explorer, reviewer, docs-researcher |
 

tests/scripts/codex-hooks.test.js

@@ -918,6 +918,12 @@ if (
       const parsed = TOML.parse(merged);
       assert.strictEqual(parsed.mcp_servers['chrome-devtools'].command, 'npx');
       assert.deepStrictEqual(parsed.mcp_servers['chrome-devtools'].args, ['chrome-devtools-mcp@1.10.1']);
+      const rootMcp = JSON.parse(fs.readFileSync(path.join(repoRoot, '.mcp.json'), 'utf8'));
+      const rootPackages = rootMcp.mcpServers['chrome-devtools'].args.filter(arg =>
+        arg.startsWith('chrome-devtools-mcp@'));
+      assert.deepStrictEqual(rootPackages, parsed.mcp_servers['chrome-devtools'].args,
+        'root MCP and generated Codex TOML must use the same connector pin');
+      assert.deepStrictEqual(rootPackages, ['chrome-devtools-mcp@1.10.1']);
       assert.strictEqual(parsed.mcp_servers['chrome-devtools'].startup_timeout_sec, 30);
       // No retired server may be (re-)emitted — exa's url form broke Codex (#2224).
       assert.strictEqual(parsed.mcp_servers.exa, undefined);
@@ -937,6 +943,51 @@ if (
   passed++;
 else failed++;
 
+if (
+  test('merge-mcp-config preserves an existing latest entry until explicit recommendation refresh', () => {
+    const tempDir = createTempDir('mcp-merge-explicit-refresh-');
+    const configPath = path.join(tempDir, 'config.toml');
+    const original = [
+      '# User-maintained configuration',
+      '[mcp_servers.chrome-devtools]',
+      'command = "npx"',
+      'args = ["chrome-devtools-mcp@latest", "--custom-browser-argument"]',
+      'startup_timeout_sec = 75',
+      '[mcp_servers.chrome-devtools.env]',
+      'CUSTOM_BROWSER_SETTING = "preserve-until-explicit-refresh"',
+      '',
+      '[mcp_servers.user_tool]',
+      'command = "custom-launcher"',
+      'args = ["--user-setting"]',
+      '',
+    ].join('\n');
+
+    try {
+      fs.writeFileSync(configPath, original);
+      const preserved = runNode(mergeMcpConfigScript, [configPath], deterministicPackageEnv);
+      assert.strictEqual(preserved.status, 0, `${preserved.stdout}\n${preserved.stderr}`);
+      assert.match(preserved.stderr, /chrome-devtools differs from ECC recommendation/);
+      assert.match(preserved.stderr, /--update-mcp to refresh/);
+      assert.strictEqual(fs.readFileSync(configPath, 'utf8'), original,
+        'normal sync must preserve existing latest and customized settings byte-for-byte');
+
+      const refreshed = runNode(mergeMcpConfigScript, [configPath, '--update-mcp'], deterministicPackageEnv);
+      assert.strictEqual(refreshed.status, 0, `${refreshed.stdout}\n${refreshed.stderr}`);
+      assert.match(refreshed.stdout, /\[update\] mcp_servers\.chrome-devtools/);
+      const updated = TOML.parse(fs.readFileSync(configPath, 'utf8'));
+      assert.deepStrictEqual(updated.mcp_servers['chrome-devtools'], {
+        command: 'npx', args: ['chrome-devtools-mcp@1.10.1'], startup_timeout_sec: 30,
+      }, 'explicit refresh replaces the whole recommended section, including custom subsettings');
+      assert.deepStrictEqual(updated.mcp_servers.user_tool, TOML.parse(original).mcp_servers.user_tool,
+        'unrelated user-managed server settings remain untouched');
+    } finally {
+      cleanup(tempDir);
+    }
+  })
+)
+  passed++;
+else failed++;
+
 if (
   test('merge-mcp-config repairs the invalid exa url entry from earlier ECC versions (#2224)', () => {
     const tempDir = createTempDir('mcp-merge-exa-repair-');