2 files changed, 27 insertions, 0 deletions

diff --git a/docs/DEFAULTS.md b/docs/DEFAULTS.md
index 3986654..3d1a863 100644
--- a/docs/DEFAULTS.md
+++ b/docs/DEFAULTS.md
@@ -27,7 +27,18 @@ srd.set("general.file_manager", "")                    -- Default: "" - empty me
 srd.set("general.desktop_icon_single_click", false)    -- Default: false - double-click opens an icon
 srd.set("general.terminal", "")                        -- Default: "" - empty tries a common terminal on $PATH
 srd.set("general.phone_mode", false)                   -- Default: false - see "Phone mode" below
+srd.set("general.close_focus_follows_workspace", false) - Default: false - see below
 ```
+
+`close_focus_follows_workspace` decides what happens when your currently
+focused window closes and no other window is left on the workspace you're
+looking at. `false` (the default) leaves you with nothing focused on your
+own workspace - it never switches you elsewhere, matching Windows/GNOME/
+macOS, none of which change your active workspace just because a window
+closed. `true` restores the alternate behaviour: falling back to whichever
+window was focused most recently anywhere, switching your active workspace
+to follow it there (matching Hyprland's own `focuswindow`-driven
+convention). Live-settable: `srd set close_focus_follows_workspace <bool>`.
 `general.smart_placement`/`general.border_width` are not listed: neither
 is implemented - new-window placement always uses smart placement
 unconditionally (no toggle exists), and the real, working border-width
diff --git a/docs/TODO.md b/docs/TODO.md
index 71e3e59..c533d39 100644
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -1,5 +1,21 @@
 # TODO / planned features - master checklist
 
+## Four live reports from a real second monitor: one diagnosis, two real fixes, one config toggle, one AGS-side finding (2026-08-28)
+
+A second monitor was physically connected, surfacing several reports at once.
+
+**"Windows show a bit in the other monitor", diagnosed, not yet independently re-verified.** `srd clients` on the live session showed several real windows sitting at `x: 1920` - exactly the seam between the two 1920-wide outputs. With shadows still active on the (not-yet-restarted) live binary, each one's 24px shadow strip has nowhere to land but the neighbouring monitor. This is a real, separate gap from anything fixed earlier today: the shadow-tint fix only ever considered a window's *neighbouring tile*, never a *neighbouring monitor* - `shadow_rect` expands blindly by `SHADOW_SIZE` on every side with no monitor-boundary awareness at all, so any floating window near a multi-monitor seam would still bleed onto the adjacent screen even with today's other shadow fixes applied. Not fixed as its own thing, since `general.shadows` was already turned off for this user's own live config today (per their own "tinting no" - see the shadow-regression entry below) - moot for them specifically, but a real, still-open limitation worth flagging for anyone who re-enables shadows on a multi-monitor setup.
+
+**Desktop icons stayed highlighted after clicking a window - fixed.** `select_desktop_icon(None)` (clearing the selection) was only ever called from `start_desktop_marquee` (starting a fresh rubber-band select on bare desktop) - never from anywhere a real window becoming focused would reach. Every focus path in this compositor (a click, Alt-Tab, a dock's IPC focus dispatch, scratchpad show, the Snap-Layouts flyout) already funnels through one shared `focus_window` in `crates/wayland/src/input/focus.rs` for raising - added the same deselect call there, so it's now correct regardless of *how* a window got focused, matching Windows/GNOME/macOS convention (a selected icon stays highlighted only until something else takes focus).
+
+**Closing a window "teleported" the user to a different workspace - root-caused and fixed, with a new config toggle.** `WindowManager::remove_window`'s own fallback, when the closed window was the focused one, picked `self.order.last()` - but `self.order` tracks every window *globally*, not per-workspace, so that fallback could just as easily land on a background window sitting on a completely different workspace. `focus_window` already switches the active workspace to match whatever it's given (a real, separate, correct feature for a deliberate `srd dispatch focus` from elsewhere, fixed earlier this project's history) - handing it a cross-workspace fallback here silently dragged the user's entire view along with it the instant they closed a window. Fixed by preferring the most-recently-focused window still on the *current* workspace first; a new `general.close_focus_follows_workspace` (default `false`, live-settable via `srd set`) decides what happens only when there's truly nothing left on the current workspace to fall back to - `false` leaves focus at nothing (matching every mainstream desktop, none of which change your active workspace just because a window closed), `true` restores the original always-follow-the-global-fallback behaviour for anyone who wants Hyprland's own convention instead. Three new tests covering same-workspace preference, the off default, and the opt-in follow behaviour.
+
+**AGS/waybar/aegis not auto-loading a bar on the newly connected monitor - investigated, srdwm's own side confirmed correct.** `srd monitors` immediately showed the new output (`HDMI-A-1`), positioned and enabled correctly - `reprobe_outputs`' hotplug path really did create a real `wl_output` global and push a `CoreEvent::MonitorAdded`, and `srd subscribe` already emits a `monitors` event specifically for this (added in an earlier session at the AGS side's own request, precisely so a panel wouldn't need to poll). Everything this compositor is responsible for advertising is being advertised correctly. If a panel still doesn't create a bar on the new output, the gap is very likely that panel's own monitor-added reactivity (many bar toolkits enumerate outputs once at their own startup and never re-scan), not anything srdwm failed to tell it - raised with the peer sessions that own those tools rather than guessed at or fixed here, since this compositor has no way to reach into another process's own window-creation logic.
+
+**Also owned directly, not fixed:** two accidental live-session side effects from testing Firefox/Nemo's own decoration earlier in this same stretch - both are single-instance apps that activate against whatever instance is already running regardless of a `WAYLAND_DISPLAY` override on the new invocation, opening real new windows on the user's actual desktop instead of the intended nested test instance. Told to the user directly as soon as noticed; neither window was closed without being asked.
+
+Full workspace build/test/clippy clean (247 core tests, +3 for the close-focus-workspace fix; 152 wayland, unchanged - the desktop-icon fix is one line inside a function too tightly coupled to `CompState`/smithay to unit-test in isolation, same class of gap this project's own testing convention already accepts elsewhere).
+
 ## Zathura double-titlebar: same class of bug as Firefox/Nemo, heuristic broadened to catch it (2026-08-28)
 
 Reported live: "also noticed double title bars in zathura. i hope there aren't more programs experiencing this" - while checking the user's own live session for an unrelated reason, a screenshot of their real, already-open Zathura window showed two stacked title rows with two *visibly different* button styles (plain X/minus/square icons on top, filled traffic-light-style dots directly underneath) - the same tell the Firefox/Nemo double-decoration bug always had: srdwm's own server-side titlebar, with zathura's own girara-drawn header underneath it, unsuppressed.