@@ -35,6 +35,31 @@
 logger = logging.getLogger(__name__)
 
 
+def _deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge `overlay` onto `base`, returning a new dict.
+
+    Semantics:
+    - Dicts merge recursively.
+    - Lists, scalars, and `None` from `overlay` replace the corresponding
+      value in `base`.
+    - Neither input is mutated; a fresh dict is returned.
+    - Keys present only in `base` are preserved as-is.
+
+    Module-private helper for PluginManager.merge_app_config. Intentionally
+    NOT exposed as a public utility (Q3 constraint, design doc): consumers
+    who need different merge semantics pre-compute their own merged dict
+    and use refresh_config with it.
+    """
+    out: dict[str, Any] = dict(base)
+    for key, overlay_value in overlay.items():
+        base_value = out.get(key)
+        if isinstance(base_value, dict) and isinstance(overlay_value, dict):
+            out[key] = _deep_merge(base_value, overlay_value)
+        else:
+            out[key] = overlay_value
+    return out
+
+
 class PluginManager:
     """Central manager for plugin discovery, lifecycle, and hooks.
 
@@ -139,24 +164,41 @@ def reload_config(self) -> None:
         self._i18n = I18n(self._config_dir, default_lang=default_lang)
         logger.info("Reloaded config from %s", self._config_path)
 
-    def refresh_config(self, new_app_config: dict[str, Any] | None = None) -> list[PluginError]:
-        """Replace the app-config snapshot and notify active plugins.
+    def refresh_config(
+        self,
+        new_app_config: dict[str, Any] | None = None,
+        *,
+        notify: bool = True,
+    ) -> list[PluginError]:
+        """Replace the app-config snapshot and (by default) notify active plugins.
 
         Replaces both the manager's snapshot and each active plugin's
-        self.app_config reference, then calls plugin.on_config_changed(old, new)
-        for each. Plugins that do not override the hook are still notified
-        (the default is a no-op).
+        self.app_config reference. When `notify=True` (the default), calls
+        plugin.on_config_changed(old, new) on each active plugin. Plugins
+        that do not override the hook are still notified (the default is a
+        no-op).
 
         Failures in on_config_changed do not stop other plugins from being
         notified; they are collected and returned.
 
+        Distinction from merge_app_config (v0.10.0): refresh_config REPLACES
+        the entire snapshot with the caller-supplied dict. Any pre-existing
+        keys not present in `new_app_config` are LOST. Use merge_app_config
+        when you want overlay semantics that preserve unmentioned keys.
+
         Args:
             new_app_config: If provided, replaces the snapshot directly. If
                 None, reloads app.yaml from disk (and refreshes i18n).
+            notify: When True (default), call on_config_changed on each active
+                plugin. When False, replace the snapshot silently and return
+                []. Set False during startup BEFORE discover_plugins() when no
+                plugins are active to notify, or when a caller wants to swap
+                the snapshot without triggering hooks.
 
         Returns:
             List of PluginError entries from plugins whose on_config_changed
-            raised. Empty list when all hooks succeeded.
+            raised. Empty list when all hooks succeeded, when notify=False,
+            or when no plugins are active.
         """
         old = self._app_config
 
@@ -169,6 +211,71 @@ def refresh_config(self, new_app_config: dict[str, Any] | None = None) -> list[P
 
         self._app_config = new
 
+        if not notify:
+            logger.info("Refreshed app config; notify=False, no plugins notified")
+            return []
+
+        return self._notify_plugins_of_config_change(old, new)
+
+    def merge_app_config(
+        self,
+        overlay: dict[str, Any],
+        *,
+        notify: bool = True,
+    ) -> list[PluginError]:
+        """Deep-merge `overlay` onto the current app-config snapshot.
+
+        Merge semantics: dicts merge recursively; lists, scalars, and `None`
+        replace. Matches the standard YAML-overlay pattern used by consumers
+        layering a user-overlay YAML, a secrets file, and env-var overrides
+        on top of the project's app.yaml.
+
+        When `notify=True` (the default), each active plugin's
+        on_config_changed(old, new) is called with the pre- and post-merge
+        snapshots. When False, the snapshot is updated silently - appropriate
+        at startup BEFORE discover_plugins() when no plugins are active to
+        notify.
+
+        Distinction from refresh_config: merge_app_config preserves
+        pre-existing keys not mentioned in `overlay`. refresh_config replaces
+        the entire snapshot. The two methods are deliberate alternatives,
+        not aliases.
+
+        The internal deep-merge implementation is NOT exposed as a public
+        utility. Consumers who need custom merge semantics (e.g. lists
+        concatenate instead of replace) should pre-compute the merged dict
+        themselves and use refresh_config(merged_dict, notify=...).
+
+        Args:
+            overlay: Dict whose keys are merged on top of the current snapshot.
+            notify: When True (default), notify active plugins via
+                on_config_changed. When False, update silently and return [].
+
+        Returns:
+            List of PluginError entries from plugins whose on_config_changed
+            raised. Empty list when notify=False, when no plugins are active,
+            or when all hooks succeeded.
+        """
+        old = self._app_config
+        new = _deep_merge(old, overlay)
+        self._app_config = new
+
+        if not notify:
+            logger.info("Merged app config; notify=False, no plugins notified")
+            return []
+
+        return self._notify_plugins_of_config_change(old, new)
+
+    def _notify_plugins_of_config_change(
+        self, old: dict[str, Any], new: dict[str, Any]
+    ) -> list[PluginError]:
+        """Fire on_config_changed for each active plugin.
+
+        Internal helper shared by refresh_config and merge_app_config. Updates
+        each plugin's self.app_config reference, calls the hook, records any
+        failures, and on success updates last_config_change + fires the
+        on_config_refreshed event.
+        """
         errors: list[PluginError] = []
         active_plugins = self._lifecycle.get_active_plugins()
         for plugin in active_plugins:
@@ -198,7 +305,7 @@ def refresh_config(self, new_app_config: dict[str, Any] | None = None) -> list[P
                 self._plugin_states[plugin.name] = replace(tracked, last_config_change=now)
             self._fire_config_refreshed(plugin.name, old, new)
 
-        logger.info("Refreshed app config; notified %d active plugin(s)", len(active_plugins))
+        logger.info("Notified %d active plugin(s) of config change", len(active_plugins))
         return errors
 
     def list_available_plugins(self) -> list[str]:
 
@@ -184,3 +184,199 @@ def test_nested_compared_by_equality(self) -> None:
     def test_identical_nested_omitted(self) -> None:
         diff = config_diff({"a": {"k": 1}}, {"a": {"k": 1}})
         assert diff == {}
+
+
+class TestRefreshConfigNotifyKwarg:
+    """v0.10.0 C3: refresh_config(notify=False) replaces snapshot silently."""
+
+    def test_notify_false_does_not_fire_hooks(self, tmp_path: Path) -> None:
+        cfg = _write_config(tmp_path, ["recording"])
+        pm = PluginManager(config_path=str(cfg))
+        pm.register_plugins([RecordingPlugin])
+
+        plugin = pm.get_plugin("recording")
+        assert isinstance(plugin, RecordingPlugin)
+        assert plugin.changes == []
+
+        new_cfg = {"app": {"name": "Silent"}, "plugins": {"enabled": ["recording"]}}
+        errors = pm.refresh_config(new_cfg, notify=False)
+
+        # Snapshot replaced ...
+        assert pm.get_app_config()["app"]["name"] == "Silent"
+        # ... but no hook fired.
+        assert plugin.changes == []
+        # ... and no errors returned (always [] under notify=False).
+        assert errors == []
+
+
+class TestMergeAppConfig:
+    """v0.10.0 C3: merge_app_config(overlay, *, notify=True)."""
+
+    def test_pre_discovery_overlay_no_active_plugins(self, tmp_path: Path) -> None:
+        """Case 1: notify=False, zero active plugins. Returns [], no hooks."""
+        cfg = _write_config(tmp_path, [])
+        pm = PluginManager(config_path=str(cfg))
+        # Deliberately no register_plugins. No plugins are active.
+
+        errors = pm.merge_app_config({"feature": {"enabled": True}}, notify=False)
+
+        assert errors == []
+        # Snapshot mutated.
+        assert pm.get_app_config()["feature"] == {"enabled": True}
+        # Pre-existing keys preserved.
+        assert pm.get_app_config()["app"]["name"] == "T"
+
+    def test_post_discovery_overlay_notifies_active_plugins(self, tmp_path: Path) -> None:
+        """Case 2: notify=True (default), active plugins fire on_config_changed,
+        last_config_change updates."""
+        cfg = _write_config(tmp_path, ["recording"])
+        pm = PluginManager(config_path=str(cfg))
+        pm.register_plugins([RecordingPlugin])
+
+        plugin = pm.get_plugin("recording")
+        assert isinstance(plugin, RecordingPlugin)
+        assert plugin.changes == []
+
+        # Before-snapshot lacks last_config_change.
+        insp_before = pm.inspect_plugin("recording")
+        assert insp_before is not None
+        assert insp_before.state.last_config_change is None
+
+        errors = pm.merge_app_config({"feature": {"enabled": True}})
+
+        assert errors == []
+        assert len(plugin.changes) == 1
+        old, new = plugin.changes[0]
+        assert "feature" not in old
+        assert new["feature"] == {"enabled": True}
+        # Pre-existing keys preserved in the new snapshot.
+        assert new["app"]["name"] == "T"
+
+        # last_config_change updated.
+        insp_after = pm.inspect_plugin("recording")
+        assert insp_after is not None
+        assert insp_after.state.last_config_change is not None
+
+    def test_merge_semantic_dict_recursive_list_replace_scalar_replace(
+        self, tmp_path: Path
+    ) -> None:
+        """Case 3: dicts merge recursively; lists, scalars, None replace."""
+        cfg = _write_config(
+            tmp_path,
+            [],
+            extras={
+                "ai": {"provider": "edge", "models": ["m1", "m2"], "enabled": True},
+                "scalar_key": "baseline",
+                "none_key": "baseline",
+            },
+        )
+        pm = PluginManager(config_path=str(cfg))
+
+        pm.merge_app_config(
+            {
+                "ai": {"models": ["m3"], "new_field": 42},  # dict merges; list replaces
+                "scalar_key": "overridden",  # scalar replaces
+                "none_key": None,  # None replaces
+            },
+            notify=False,
+        )
+
+        merged = pm.get_app_config()
+        # Dict recursive: provider preserved, models replaced, new_field added.
+        assert merged["ai"]["provider"] == "edge"
+        assert merged["ai"]["models"] == ["m3"]
+        assert merged["ai"]["enabled"] is True
+        assert merged["ai"]["new_field"] == 42
+        # Scalar + None replace.
+        assert merged["scalar_key"] == "overridden"
+        assert merged["none_key"] is None
+
+    def test_empty_overlay_still_fires_hooks(self, tmp_path: Path) -> None:
+        """Case 4: merge_app_config({}) is intentionally NOT a no-op for
+        active plugins. The snapshot reference changes (a fresh dict via
+        _deep_merge) and on_config_changed fires with old==new (by value).
+        Consumers expecting a strict no-op should not call merge_app_config
+        with an empty overlay; use refresh_config(None, notify=False) to
+        get a true no-op."""
+        cfg = _write_config(tmp_path, ["recording"])
+        pm = PluginManager(config_path=str(cfg))
+        pm.register_plugins([RecordingPlugin])
+
+        plugin = pm.get_plugin("recording")
+        assert isinstance(plugin, RecordingPlugin)
+        assert plugin.changes == []
+
+        errors = pm.merge_app_config({})
+
+        assert errors == []
+        assert len(plugin.changes) == 1
+        old, new = plugin.changes[0]
+        # By value: identical. By identity: fresh dict (the new merged result).
+        assert old == new
+        assert old is not new
+
+    def test_merge_vs_replace_semantic_distinction(self, tmp_path: Path) -> None:
+        """Case 6: merge_app_config preserves keys not in overlay;
+        refresh_config drops keys not in new_app_config. Pins the documented
+        difference between the two methods against accidental refactors."""
+        cfg = _write_config(
+            tmp_path,
+            [],
+            extras={"baseline_key": "kept", "ai": {"provider": "edge"}},
+        )
+
+        # merge_app_config path: baseline_key survives.
+        pm_merge = PluginManager(config_path=str(cfg))
+        pm_merge.merge_app_config({"new_key": "added"}, notify=False)
+        merged = pm_merge.get_app_config()
+        assert merged["baseline_key"] == "kept"
+        assert merged["new_key"] == "added"
+        assert merged["ai"]["provider"] == "edge"
+
+        # refresh_config path: baseline_key is gone.
+        pm_replace = PluginManager(config_path=str(cfg))
+        pm_replace.refresh_config({"new_key": "added"}, notify=False)
+        replaced = pm_replace.get_app_config()
+        assert "baseline_key" not in replaced
+        assert replaced["new_key"] == "added"
+        assert "ai" not in replaced
+
+    def test_failing_on_config_changed_collected_as_plugin_error(self, tmp_path: Path) -> None:
+        """Same error-collection contract as refresh_config: failing hooks
+        produce PluginError entries but do not stop the loop."""
+        cfg = _write_config(tmp_path, ["failing_change", "recording"])
+        pm = PluginManager(config_path=str(cfg))
+        pm.register_plugins([FailingOnChangePlugin, RecordingPlugin])
+
+        recording = pm.get_plugin("recording")
+        assert isinstance(recording, RecordingPlugin)
+
+        errors = pm.merge_app_config({"feature": "x"})
+
+        assert len(errors) == 1
+        assert errors[0].name == "failing_change"
+        assert errors[0].phase == "config_refresh"
+        assert isinstance(errors[0].cause, RuntimeError)
+        # The recording plugin still got notified despite the failing peer.
+        assert len(recording.changes) == 1
+
+    def test_merge_after_deactivate_all_is_safe(self, tmp_path: Path) -> None:
+        """Case 7 (user-requested): merge_app_config after deactivate_all.
+        Zero active plugins, notify=True. Returns []. No hooks fired. No crash."""
+        cfg = _write_config(tmp_path, ["recording"])
+        pm = PluginManager(config_path=str(cfg))
+        pm.register_plugins([RecordingPlugin])
+
+        plugin = pm.get_plugin("recording")
+        assert isinstance(plugin, RecordingPlugin)
+
+        pm.deactivate_all()
+        assert plugin.changes == []
+
+        # notify=True default, but no active plugins remain.
+        errors = pm.merge_app_config({"feature": "x"})
+
+        assert errors == []
+        assert plugin.changes == []  # plugin was deactivated; not notified.
+        # Snapshot was still merged.
+        assert pm.get_app_config()["feature"] == "x"