diff --git a/AGENTS.md b/AGENTS.md
index d316add..28af622 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -199,6 +199,32 @@ Workflow:
 - All configuration options are documented in `src/mtproto_proxy.app.src`.
 - Config can be reloaded without restart: `make update-sysconfig && systemctl reload mtproto-proxy`.
 
+## Debugging
+
+### Enabling debug logs for a single module at runtime
+
+The primary log level is `info`. To see `?LOG_DEBUG` messages from one module without
+flooding the log with debug output from all of OTP:
+
+```erlang
+% In the running Erlang shell (e.g. via: sudo /opt/personal_mtproxy/bin/mtproto_proxy remote_console)
+logger:set_module_level(mtp_handler, debug).   % override primary gate for this module only
+logger:set_handler_config(default, level, debug).  % let the file handler pass debug through
+```
+
+This works because `set_module_level` bypasses the primary level check *only* for the
+named module — no other module's debug messages are affected. The handler level change
+is required because the `default` file handler has its own `level => info` guard.
+
+To revert:
+
+```erlang
+logger:unset_module_level(mtp_handler).
+logger:set_handler_config(default, level, info).
+```
+
+Both settings are in-memory only and reset on restart.
+
 ## Security Considerations
 
 - Do **not** commit real secrets, tags, or credentials into config files.
diff --git a/src/mtp_down_conn.erl b/src/mtp_down_conn.erl
index b3a4f39..436b957 100644
--- a/src/mtp_down_conn.erl
+++ b/src/mtp_down_conn.erl
@@ -171,6 +171,7 @@ handle_info({tcp_closed, Sock}, #state{sock = Sock, upstreams = Ups, pool = Pool
         0 ->
             {stop, {shutdown, downstream_socket_closed}, State};
         N ->
+            %% See ../doc/migration-flow.md
             %% Remove self from pool first so no new upstreams can be assigned.
             ok = mtp_dc_pool:downstream_closing(Pool, self()),
             ?LOG_INFO("Downstream socket closed with ~p active client(s); migrating", [N]),
diff --git a/src/mtp_handler.erl b/src/mtp_handler.erl
index f2df969..b29a526 100644
--- a/src/mtp_handler.erl
+++ b/src/mtp_handler.erl
@@ -80,6 +80,7 @@ keys_str() ->
 send(Upstream, Packet) ->
     gen_server:cast(Upstream, Packet).
 
+%% See doc/migration-flow.md
 -spec migrate(pid(), OldDown :: mtp_down_conn:handle()) -> ok.
 migrate(Upstream, OldDown) ->
     gen_server:cast(Upstream, {migrate, OldDown}).