diff --git a/architecture/build.md b/architecture/build.md
index 639dde8ba8..a164f9aaa7 100644
--- a/architecture/build.md
+++ b/architecture/build.md
@@ -226,6 +226,8 @@ The Homebrew service keeps gateway TLS under the Homebrew state directory but
 mirrors Docker sandbox client TLS into `$HOME/.local/state/openshell/homebrew/tls`
 at service start, because Docker Desktop bind mounts must use paths visible to
 the macOS user's shared home directory.
+On upgrade, the formula atomically replaces only exact package-generated
+schema-v1 gateway configs, leaving user-edited configs untouched.
 
 Local image work should use `mise` tasks rather than direct Docker commands so
 the same staging and tagging assumptions are used locally and in CI.
diff --git a/python/openshell/release_formula_test.py b/python/openshell/release_formula_test.py
index 4db21b0951..e1bc1c9c54 100644
--- a/python/openshell/release_formula_test.py
+++ b/python/openshell/release_formula_test.py
@@ -100,7 +100,8 @@ def test_generate_homebrew_formula_uses_channel_urls_and_exact_version(
     assert 'bind_address = "[::1]:17670"' in legacy_ipv6_config.group("contents")
     assert "gateway_config.read == legacy_empty_gateway_config_contents ||" in formula
     assert "gateway_config.read == legacy_ipv6_gateway_config_contents" in formula
-    assert "gateway_config.write gateway_config_contents" in formula
+    assert formula.count("gateway_config.write gateway_config_contents") == 1
+    assert "gateway_config.atomic_write gateway_config_contents" in formula
     assert '# compute_driver = "vm"' not in formula
     assert (
         "openshell gateway add https://localhost:17670 --local --name openshell"
diff --git a/tasks/scripts/release.py b/tasks/scripts/release.py
index 78695824c2..4d76f13048 100644
--- a/tasks/scripts/release.py
+++ b/tasks/scripts/release.py
@@ -448,7 +448,7 @@ def post_install
       # Keep any user-edited config untouched.
       if gateway_config.read == legacy_empty_gateway_config_contents ||
          gateway_config.read == legacy_ipv6_gateway_config_contents
-        gateway_config.write gateway_config_contents
+        gateway_config.atomic_write gateway_config_contents
       end
     end