docs: inform users that updating OpenChrome does not migrate MCP host configs

[shaun0927]

Goal

Make the post-update action for safe parallel MCP sessions explicit to users: installing a new openchrome-mcp version can add broker / auto-elect capabilities, but it does not rewrite existing Claude Code, Codex CLI, OpenCode, or other MCP host registrations. Users must run the relevant setup/config command and restart their host session before the new topology is active.

Final Implementation Scope

• Add user-facing documentation that clearly distinguishes:
  • package update (npm install -g openchrome-mcp@latest / npm update -g openchrome-mcp), and
  • host configuration update (openchrome setup --client <host> ..., or documented manual config).
• Surface this distinction in the main README and topology documentation where users look when parallel sessions fail.
• Add release-note style wording that future releases can reuse as an "Action required" block.
• Keep the guidance host-neutral: Claude Code, Codex CLI, OpenCode, and any stdio MCP host must be covered without implying hidden host-specific behavior.
• Link the guidance to the duplicate-controller / broker / auto-elect problem space tracked by Parallel sessions deadlock on controller lock: half-zombie owner holds lock forever, host sees only -32000 #1474 and Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480.

Success Criteria

• A user who upgrades OpenChrome and still has an old direct MCP config can understand why the behavior did not change automatically.
• The docs explicitly state that active MCP host sessions must be restarted after setup/config changes.
• The docs provide copy-pasteable commands for the supported setup paths, while leaving room for the exact topology flag name that lands in Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480.
• The docs do not promise that npm install -g openchrome-mcp@latest mutates Claude/Codex/OpenCode configs.
• The docs do not make auto-elect the default unless the implementation PRs actually do so.

Verification Method

• Read-only doc review: confirm README and topology docs contain the update-vs-config distinction.
• Command-text review: confirm each setup example names the host client and mentions restart.
• Regression check: confirm no runtime defaults, generated config, or CLI behavior changes are introduced by the docs-only PR.
• Link check: confirm issue references to Parallel sessions deadlock on controller lock: half-zombie owner holds lock forever, host sees only -32000 #1474 and Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480 are present and accurate.

Guardrails

• Do not silently rewrite user host configs from package install hooks.
• Do not add postinstall behavior that edits Claude, Codex, OpenCode, or global MCP config files.
• Do not encourage unsafe shared direct-controller attachment as a normal path.
• Do not claim that existing active sessions can load a newly configured MCP namespace without restart.
• Do not collapse distinct topologies: direct isolated profiles, explicit broker, and future auto-elect should remain visibly separate.

Explicit Non-Goals

• No implementation of auto-elect itself in this issue.
• No CLI behavior change unless a separate follow-up PR deliberately updates openchrome setup, openchrome doctor, or duplicate-controller remediation.
• No npm lifecycle script that mutates host configuration.
• No promise that every third-party MCP host supports the same setup command.
• No replacement of the explicit broker topology docs.

Implementation Approach

1. Add a concise README note near installation / setup explaining: update installs capabilities; setup activates them in host config; restart is required.
2. Add a troubleshooting/action-required note near the parallel sessions section.
3. Update docs/mcp/topologies.md with a dedicated "After upgrading" subsection for users who expect the npm update alone to fix duplicate-controller failures.
4. Optionally add release-note wording for the next release once Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480 lands.
5. Keep the wording future-proof by describing the current explicit broker path and the future/opt-in auto-elect path without assuming default behavior.

PR Decomposition

• PR A — Documentation inform path: README + topology docs + release-note template wording. No runtime changes.
• PR B — Setup/doctor inform path: teach openchrome setup / openchrome doctor to detect old direct configs and recommend the safe topology. Separate because it touches CLI behavior.
• PR C — MCP-visible remediation copy: align duplicate-controller degraded response text with the same update-vs-config guidance. Separate because it depends on feat(observability): surface DuplicateController remediation over MCP instead of bare -32000 (#1474) #1479 / Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480 runtime surfaces.

Over-Engineering Checklist

• Is this solved with documentation before adding CLI automation? Yes, start with docs.
• Are we adding a config migration daemon? No.
• Are we editing user files from npm install? No.
• Are we adding host-specific hidden behavior? No.
• Are we creating a new topology? No, only documenting activation of existing / in-flight topologies.

Drift-Prevention Checklist

• README, README.ko, and docs/mcp/topologies.md should not contradict each other.
• If Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480 changes the final flag name or default behavior, update all examples in one PR before release.
• If auto-elect becomes default, rewrite the action-required block to say when setup is still needed for existing configs.
• If setup command syntax changes, update both English and Korean docs together.
• Keep the guidance tied to the product SSOT (SSOT: OpenChrome as a host-neutral MCP browser harness #1359): MCP protocol boundary first, host-specific setup second.

Language Boundary

• Primary issue and PR text should be English.
• README English should carry the canonical wording.
• README.ko may provide a Korean translation, but it must not introduce different semantics.
• CLI/user-facing diagnostics should prefer short English text unless a localized surface is explicitly added.

Critical Risk Review

• Risk: users believe npm update alone fixes existing sessions. Mitigation: state package update vs host config update explicitly.
• Risk: users expect active sessions to hot-load MCP changes. Mitigation: state host restart is required.
• Risk: docs imply --auto-elect is stable/default before the PR stack lands. Mitigation: phrase as opt-in / after the feature is available.
• Risk: users copy unsafe direct shared config. Mitigation: prefer isolated profiles or broker/auto-elect; discourage multiple direct controllers for one profile.
• Risk: host-specific instructions drift. Mitigation: centralize topology explanation and link setup examples back to it.

Definition of Done

• English README explains that update installs capability but setup/config activates topology.
• Parallel-session docs explain that existing direct configs must be migrated or replaced.
• Topology docs include an "after upgrading" action path and restart requirement.
• PR body links this issue, Parallel sessions deadlock on controller lock: half-zombie owner holds lock forever, host sees only -32000 #1474, and Parallel multi-session is blocked by design — land the #1474 self-healing stack + make the opt-in broker path reachable (SSOT #1359 / audit #1457 alignment) #1480.
• No runtime files are changed in the docs-only PR.
• Verification confirms the PR is documentation-only and internally consistent.