Correct stale comments and document non-obvious logic

Author: mgxv

Sources/AdapterClient.swift

@@ -22,7 +22,8 @@
 // continuations so the consumer loops exit.
 //
 // `fetchNowPlayingOnce` at the bottom runs the adapter in one-shot
-// `get` mode for `status`.
+// `get` mode to prime the controller's first evaluation at startup
+// and on wake.
 
 import Foundation
 import os
@@ -279,8 +280,9 @@ actor AdapterClient {
 
 // MARK: - One-shot fetch (status command)
 
-/// Synchronous one-shot `mediaremote-adapter.pl get` for the
-/// `status` subcommand. Blocks until the subprocess exits.
+/// Synchronous one-shot `mediaremote-adapter.pl get` used to prime
+/// Now Playing state at startup and on wake. Blocks until the
+/// subprocess exits.
 ///
 /// `get` emits the raw payload dict (or JSON `null`), not the
 /// `{type, payload}` envelope that `stream` uses.

Sources/Commands.swift

@@ -1,6 +1,6 @@
 // Implementations of the CLI verbs: (default) foreground run,
-// `status`, `logs`, `version`, `help`. LaunchAgent lifecycle is
-// delegated to Homebrew (`brew services`).
+// `status`, `mode`, `deny`, `logs`, `version`, `help`. LaunchAgent
+// lifecycle is delegated to Homebrew (`brew services`).
 
 import AppKit
 import Foundation

Sources/FixedController.swift

@@ -28,6 +28,8 @@ final class FixedController {
 
     private func toggle() {
         isHidden.toggle()
+        // Fixed mode has no fullscreen signal; pass isFullScreen: true so
+        // apply()'s FS guard always lets the write through.
         menuBar.apply(shouldHide: isHidden, isFullScreen: true)
         let verb = isHidden ? "hide" : "show"
         Log.controller.info("→ \(verb, privacy: .public)  trig=hotkey mode=fixed")

Sources/HotkeyWatcher.swift

@@ -36,7 +36,8 @@ final class HotkeyWatcher {
 
     // MARK: Lifecycle
 
-    /// Returns false if the chord is already taken; non-fatal — the
+    /// Returns false if registration fails — most often because the
+    /// chord is already claimed by another app. Non-fatal: the
     /// daemon's automatic control still works without it.
     func start(chord: Chord = defaultChord) -> Bool {
         guard handlerRef == nil else { return true }

Sources/SmartController.swift

@@ -107,7 +107,8 @@ final class SmartController: NSObject {
     private var appOverrides: AppOverrides = .empty
 
     /// Hotkey-driven override. Cleared only on Desktop arrival;
-    /// survives front-app switches, FS↔FS hops, and play/pause.
+    /// survives front-app switches, FS↔FS hops, play/pause, and
+    /// sleep/wake.
     var overrule: Overrule = .auto
 
     private var lastSnapshot: Snapshot?
@@ -279,7 +280,9 @@ final class SmartController: NSObject {
 
     /// Single point of integration — every input channel funnels
     /// here. The `trigger` is preserved through to the log line so a
-    /// surprising decision can be traced back to its input.
+    /// surprising decision can be traced back to its input. `force`
+    /// bypasses the snapshot dedup to re-assert the pref even when
+    /// nothing changed (used on wake).
     private func evaluate(trigger: EvalTrigger, force: Bool = false) {
         let snap = takeSnapshot()