From 1a4e3087287cbd6eb7313842ce88402d157353da Mon Sep 17 00:00:00 2001
From: fraa2a <fraawas@proton.me>
Date: Thu, 8 Oct 2026 03:23:43 +0200
Subject: [PATCH] chore: keep comments brief and focused on caller constraints

---
 app/desktop-ui/src-tauri/src/asset_scope.rs   |   6 +-
 app/desktop-ui/src-tauri/src/clip_catalog.rs  |  12 +-
 app/desktop-ui/src-tauri/src/collections.rs   |  13 +-
 app/desktop-ui/src-tauri/src/commands.rs      |  49 +--
 app/desktop-ui/src-tauri/src/exe_icon.rs      |  17 +-
 app/desktop-ui/src-tauri/src/game_catalog.rs  |  24 +-
 app/desktop-ui/src-tauri/src/main.rs          |  18 +-
 .../src-tauri/src/settings_store.rs           |   6 +-
 app/desktop-ui/ui/src/app.tsx                 |   3 +-
 app/desktop-ui/ui/src/home/clip-card.tsx      |  12 +-
 app/desktop-ui/ui/src/home/confirm-dialog.tsx |   2 -
 app/desktop-ui/ui/src/home/detail-view.tsx    |   8 +-
 app/desktop-ui/ui/src/home/filter-menu.tsx    |   3 -
 app/desktop-ui/ui/src/home/fullscreen.tsx     |  16 +-
 app/desktop-ui/ui/src/lib/api.ts              |  16 +-
 app/desktop-ui/ui/src/lib/format.ts           |  16 +-
 app/desktop-ui/ui/src/lib/multitrack.ts       |  24 +-
 app/desktop-ui/ui/src/lib/player.ts           |   5 +-
 app/desktop-ui/ui/src/lib/settings-api.ts     |   4 +-
 .../ui/src/settings/audio-settings.tsx        |  18 +-
 app/desktop-ui/ui/src/settings/controls.tsx   |   8 -
 .../ui/src/settings/settings-popup.tsx        |  19 +-
 app/desktop-ui/ui/src/shell/titlebar.tsx      |  12 +-
 app/desktop-ui/ui/styles.css                  |  39 +--
 app/desktop-ui/vite.config.ts                 |   2 +-
 app/recorder/src/feedback_sounds.h            |   4 +-
 app/recorder/src/main.cpp                     | 309 ++++--------------
 app/recorder/src/settings_config.cpp          |  12 +-
 app/recorder/src/settings_config.h            |  26 +-
 app/recorder/src/settings_window.cpp          |   4 +-
 app/recorder/src/updater.cpp                  |   3 +-
 app/recorder/src/updater.h                    |  13 +-
 app/updater/src-tauri/src/apply.rs            |  20 +-
 app/updater/src-tauri/src/download.rs         |   5 +-
 app/updater/src-tauri/src/engine_rpc.rs       |   4 +-
 app/updater/src-tauri/src/http.rs             |   9 +-
 app/updater/src-tauri/src/main.rs             |  35 +-
 app/updater/src-tauri/src/paths.rs            |  10 +-
 app/updater/src-tauri/src/versions.rs         |  10 +-
 app/updater/ui/src/updater.tsx                |  11 +-
 app/updater/ui/styles.css                     |  28 --
 app/updater/vite.config.ts                    |   2 +-
 docs/audit/2026-10-08.md                      |  11 +-
 docs/handover/ACTIVE_HANDOVER.md              |   2 +
 libs/audio/audio.cpp                          |  39 +--
 libs/audio/audio.h                            |  44 +--
 libs/capture/capture.cpp                      |  20 +-
 libs/capture/capture.h                        |  14 +-
 libs/disk-segments/disk_segments.cpp          |   4 +-
 libs/disk-segments/disk_segments.h            |  24 +-
 libs/encoding/encoding.cpp                    |  48 +--
 libs/encoding/encoding.h                      |  66 +---
 libs/encoding/mux_common.cpp                  |   7 +-
 libs/encoding/mux_common.h                    |  21 +-
 libs/encoding/thumbnail.cpp                   |   2 -
 libs/encoding/trim.cpp                        |  12 +-
 libs/encoding/trim.h                          |  12 +-
 libs/gamelist/gamelist.cpp                    |  25 +-
 libs/gamelist/gamelist.h                      |  24 +-
 libs/ipc/ipc_server.cpp                       |  35 +-
 libs/ipc/ipc_server.h                         |  49 +--
 libs/logging/logging.cpp                      |   3 +-
 libs/logging/logging.h                        |  13 +-
 libs/replay-buffer/replay_buffer.cpp          |  14 +-
 libs/replay-buffer/replay_buffer.h            |   6 +-
 libs/storage/storage.cpp                      |  10 +-
 libs/storage/storage.h                        |  52 +--
 .../src/actions/recording-toggle.ts           |   2 +-
 plugins/stream-deck/src/plugin.ts             |   3 +-
 .../bin/actions/recording-toggle.js           |   2 +-
 .../bin/plugin.js                             |   3 +-
 71 files changed, 290 insertions(+), 1134 deletions(-)

diff --git a/app/desktop-ui/src-tauri/src/asset_scope.rs b/app/desktop-ui/src-tauri/src/asset_scope.rs
index 72c5566..ce6c78b 100644
--- a/app/desktop-ui/src-tauri/src/asset_scope.rs
+++ b/app/desktop-ui/src-tauri/src/asset_scope.rs
@@ -1,8 +1,4 @@
-// Scopes the Tauri asset protocol (asset://, exposed to the frontend via
-// convertFileSrc()) to the configured clip/recording folders, so <video>/<img>
-// tags can stream straight from disk instead of round-tripping through a local
-// HTTP server. Re-run on startup and whenever settings are saved, since the
-// output folders are user-configurable. See docs/DECISIONS.md.
+// Refresh asset permissions after output-folder changes; include .thumbs.
 
 use tauri::{AppHandle, Manager};
 
diff --git a/app/desktop-ui/src-tauri/src/clip_catalog.rs b/app/desktop-ui/src-tauri/src/clip_catalog.rs
index 108787c..eb09c46 100644
--- a/app/desktop-ui/src-tauri/src/clip_catalog.rs
+++ b/app/desktop-ui/src-tauri/src/clip_catalog.rs
@@ -74,10 +74,7 @@ fn media_folder(source: ClipSource) -> PathBuf {
     }
 }
 
-// ── Bookmarks ─────────────────────────────────────────────────────────────
-// The engine inserts bookmarks at recording-save time (timestamped live from
-// its own clock); the UI reads/edits them here. Table DDL mirrors
-// engine's storage.cpp so either side can create it (IF NOT EXISTS).
+// Bookmark sequences are 1-based within each clip.
 
 const BOOKMARK_DDL: &str = "CREATE TABLE IF NOT EXISTS clip_bookmarks (
     clip_id INTEGER NOT NULL,
@@ -173,9 +170,7 @@ fn map_clip_row(
     let game_display_name = row.get::<_, Option<String>>(6)?;
     let discord_app_id = row.get::<_, Option<String>>(9)?;
     let game_executable_path = row.get::<_, Option<String>>(10)?;
-    // Cache-only read: the clip grid must never make a synchronous network
-    // call. Artwork not yet cached shows up once the scheduled refresh
-    // (see game_catalog::refresh_stale) has run.
+    // Artwork lookup is cache-only; network refresh runs separately.
     let art = artwork.resolve(discord_app_id.as_deref(), game_process_name.as_deref());
     let video_path = folder.join(&video_file);
     let thumbnail_path = thumbnail_file.as_ref().map(|file| {
@@ -633,8 +628,7 @@ pub fn rename_clip(source: ClipSource, id: i64, new_stem: &str) -> Result<(), St
             id
         ],
     ) {
-        // Roll the filesystem back so the DB never points at files that no
-        // longer exist under their recorded names.
+        // Restore the prior filename if the catalog update fails.
         let _ = fs::rename(folder.join(&new_video), folder.join(&old_video));
         if thumb_renamed {
             let _ = fs::rename(
diff --git a/app/desktop-ui/src-tauri/src/collections.rs b/app/desktop-ui/src-tauri/src/collections.rs
index 2c6f265..e7811a6 100644
--- a/app/desktop-ui/src-tauri/src/collections.rs
+++ b/app/desktop-ui/src-tauri/src/collections.rs
@@ -1,8 +1,4 @@
-// Collections ("albums"): user-curated groupings of clips that span both
-// sources (replay + manual). Stored in a single global collections.db under
-// %LocalAppData%\Monolith - deliberately not per-catalog, because a collection
-// mixes clips from clips.db and recs.db. Rows referencing clips that have
-// since been deleted are pruned on read.
+// Collection members use (source, clip_id); IDs can overlap across catalogs.
 
 use crate::clip_catalog::{self, ClipSource};
 use crate::paths;
@@ -35,8 +31,7 @@ fn open() -> Result<Connection, String> {
     Ok(conn)
 }
 
-// UTC ISO-8601 in the same format the engine's storage layer writes
-// ("2026-08-11T12:34:56Z") so SQLite string ordering stays consistent.
+// Use UTC ISO-8601 to match the engine catalog timestamps.
 fn now_iso8601_utc() -> String {
     let secs = std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -175,9 +170,7 @@ pub fn remove_clip_from_collection(
     Ok(())
 }
 
-// Clips in a collection, most recently added first. Stale rows (the clip was
-// deleted from its catalog, or its video file is gone) are pruned here so the
-// collection never shows ghosts.
+// Prune absent clips only after all required catalogs have been read.
 pub fn collection_clips(collection_id: i64) -> Result<Vec<clip_catalog::Clip>, String> {
     let conn = open()?;
     let mut stmt = conn
diff --git a/app/desktop-ui/src-tauri/src/commands.rs b/app/desktop-ui/src-tauri/src/commands.rs
index 5eaf0fc..551da54 100644
--- a/app/desktop-ui/src-tauri/src/commands.rs
+++ b/app/desktop-ui/src-tauri/src/commands.rs
@@ -1,17 +1,4 @@
-// Tauri IPC commands invoked from the frontend via `invoke()`. Replaces the old
-// loopback HTTP `/api/*` routes (server.rs, removed) now that the window loads
-// bundled assets directly (see main.rs) and has the Tauri JS API available.
-//
-// Read-only catalog commands work without the recorder. Delete and rename
-// cross to the engine over JSON-RPC so it owns their catalog/filesystem recovery. See
-// docs/DECISIONS.md.
-//
-// IMPORTANT: every command here is `async fn`. Tauri v2 runs plain
-// (non-async) commands inline on the main thread, which is also the WebView2
-// message-pump thread - a synchronous SQLite query or engine_rpc TCP call
-// there freezes the whole window. `async fn` commands are dispatched via
-// `async_runtime::spawn`, and the blocking bodies below run on
-// `spawn_blocking` so the UI thread never waits on disk/network I/O.
+// Native Tauri commands. Run blocking disk, decode and network work through spawn_blocking.
 
 use crate::{clip_catalog, engine_rpc, game_catalog, settings_store};
 #[cfg(target_os = "windows")]
@@ -27,10 +14,7 @@ fn parse_source(source: &str) -> Result<ClipSource, String> {
     ClipSource::parse(source).ok_or_else(|| "bad source".to_string())
 }
 
-// Runs a blocking closure off the main thread and returns its value.
-// Panics inside `f` are not expected in normal operation (they'd indicate a
-// bug in the catalog/engine code, same as today), so they're surfaced by
-// unwrapping the join result rather than silently swallowed.
+// The closure runs on a blocking worker, outside the Tauri message loop.
 async fn blocking<T: Send + 'static>(f: impl FnOnce() -> T + Send + 'static) -> T {
     tauri::async_runtime::spawn_blocking(f)
         .await
@@ -48,7 +32,6 @@ async fn blocking_result<T: Send + 'static>(
         .map_err(|err| err.to_string())?
 }
 
-// ── Clip catalog (read) ───────────────────────────────────────────────────
 
 #[tauri::command]
 pub async fn list_clips(filter: ClipFilter) -> Vec<Clip> {
@@ -65,7 +48,6 @@ pub async fn distinct_hashtags() -> Vec<String> {
     blocking(clip_catalog::distinct_hashtags).await
 }
 
-// ── Engine status / recorder control (JSON-RPC to 127.0.0.1:45991) ───────
 
 #[tauri::command]
 pub async fn engine_status() -> Value {
@@ -109,7 +91,6 @@ pub async fn set_selected_game(exe: String, pid: Option<u32>) -> Result<(), Stri
     }
 }
 
-// ── Clip mutations ──────────────────────────────────────────────────────
 
 #[tauri::command]
 pub async fn clip_set_duration(source: String, id: i64, duration: f64) -> Result<(), String> {
@@ -129,7 +110,6 @@ pub async fn thumb_capture(source: String, id: i64, data_url: String) -> Result<
     })
     .await;
     if let Err(err) = &result {
-        // Surface fallback-thumbnail failures instead of silently no-opping.
         eprintln!("[thumb_capture] {source} clip {id} failed: {err}");
     }
     result
@@ -185,10 +165,7 @@ pub async fn clip_delete(source: String, id: i64) -> Result<(), String> {
     }
 }
 
-// Opens Explorer with the clip's video file pre-selected. `/select,` is an
-// Explorer-native flag (no shell interpretation of the path), so this is safe
-// against injection as long as `path` is a real filesystem path from the
-// catalog rather than arbitrary user text.
+// Explorer requires /select, and the path in separate arguments.
 #[tauri::command]
 pub async fn reveal_in_explorer(path: String) -> Result<(), String> {
     blocking_result(move || {
@@ -202,11 +179,7 @@ pub async fn reveal_in_explorer(path: String) -> Result<(), String> {
     .await
 }
 
-// Spawns the component updater (Updater.exe) with its window visible - the
-// Settings "Check for updates" action. Resolution mirrors the engine's
-// resolve_tauri_ui() (settings_window.cpp): installed exe next to the app
-// root, then the CMake build output, then a dev cargo tree. The updater has
-// its own single-instance guard, so a double spawn just focuses the window.
+// Resolve Updater.exe beside the recorder or in the development build tree.
 #[tauri::command]
 pub async fn open_updater() -> Result<(), String> {
     blocking_result(move || {
@@ -306,7 +279,6 @@ pub async fn recording_add_bookmark() -> Result<(), String> {
     }
 }
 
-// ── Bookmarks (direct SQLite writes; engine is the writer at save time) ───
 
 #[tauri::command]
 pub async fn clip_list_bookmarks(source: String, id: i64) -> Result<Vec<clip_catalog::BookmarkRow>, String> {
@@ -344,7 +316,6 @@ pub async fn clip_delete_bookmark(source: String, id: i64, seq: i64) -> Result<(
     blocking_result(move || clip_catalog::remove_bookmark(src, id, seq)).await
 }
 
-// ── Collections (global collections.db; see collections.rs) ──────────────
 
 #[tauri::command]
 pub async fn list_collections() -> Result<Vec<crate::collections::CollectionSummary>, String> {
@@ -391,17 +362,13 @@ pub async fn collection_clips(collection_id: i64) -> Result<Vec<Clip>, String> {
     blocking_result(move || crate::collections::collection_clips(collection_id)).await
 }
 
-// ── Settings ───────────────────────────────────────────────────────────
 
 #[tauri::command]
 pub async fn get_settings() -> Value {
     blocking(|| settings_store::read_config().unwrap_or(Value::Null)).await
 }
 
-// Rejects a config document that assigns the same normalized hotkey chord to
-// more than one action. Defense-in-depth mirror of the check the engine's
-// `settings::save()` also runs before persisting - this one catches it before
-// the write even happens. "NONE" (hotkey disabled) never collides with itself.
+// Ignore disabled NONE bindings when checking normalized hotkey conflicts.
 fn find_hotkey_collision(config: &Value) -> Option<String> {
     let hotkeys = config.get("hotkeys")?.as_object()?;
     let entries: [(&str, &str); 5] = [
@@ -450,9 +417,7 @@ pub async fn save_settings(app: tauri::AppHandle, config: Value) -> Result<(), S
         // (it may not be running - it reads the new values at next start).
         eprintln!("engine settings reload failed: {err}");
     }
-    // Output folders may have changed: re-scope the asset protocol so
-    // convertFileSrc() keeps working for the (possibly new) clip/recording
-    // dirs. Cheap in-memory scope update, safe to run on the main thread.
+    // Add asset permissions for the updated output folders.
     crate::asset_scope::refresh(&app);
     Ok(())
 }
@@ -476,7 +441,6 @@ pub async fn pick_folder(current: Option<String>) -> Option<String> {
     .await
 }
 
-// ── Native app icon (PNG extracted from an exe, base64 data URL) ─────────
 
 #[cfg(target_os = "windows")]
 #[tauri::command]
@@ -488,7 +452,6 @@ pub async fn exe_icon(path: String, process: String) -> Option<String> {
     .await
 }
 
-// ── Game catalog / artwork ────────────────────────────────────────────────
 
 #[tauri::command]
 pub async fn game_catalog_map() -> BTreeMap<String, CatalogEntry> {
diff --git a/app/desktop-ui/src-tauri/src/exe_icon.rs b/app/desktop-ui/src-tauri/src/exe_icon.rs
index 8a5a57e..29f8995 100644
--- a/app/desktop-ui/src-tauri/src/exe_icon.rs
+++ b/app/desktop-ui/src-tauri/src/exe_icon.rs
@@ -1,13 +1,4 @@
-// Extracts the embedded icon of a local executable and returns it as PNG bytes.
-// Used by /api/exe-icon so the UI can render the *real* application icon (title
-// bar capture status pattern) instead of remote artwork or a raw process name.
-// Windows-only by definition (SHDefExtractIconW).
-//
-// Cached in game_catalog.db keyed by process name (not install path) - see
-// game_catalog::cached_exe_icon/store_exe_icon - so the same game keeps its
-// icon across reinstalls, relocations, or different machines instead of
-// re-extracting (and never sharing a cache entry) whenever the exe's on-disk
-// path differs.
+// Extract local executable icons as PNG; this path performs no network lookup.
 
 use std::path::Path;
 
@@ -22,11 +13,7 @@ use windows::Win32::UI::WindowsAndMessaging::{DestroyIcon, GetIconInfo, HICON, I
 
 const ICON_SIZE: u32 = 64;
 
-/// PNG bytes of the executable's icon, or None when the path is not a
-/// readable executable or carries no extractable icon. `process_name` (the
-/// exe's own basename, e.g. "RocketLeague.exe") is the cache key; when it's
-/// empty the result is extracted fresh every call rather than cached, since
-/// there's no stable key to persist it under.
+/// Return None when extraction fails or the executable has no icon.
 pub fn icon_png(path: &str, process_name: &str) -> Option<Vec<u8>> {
     if process_name.is_empty() {
         return extract(path);
diff --git a/app/desktop-ui/src-tauri/src/game_catalog.rs b/app/desktop-ui/src-tauri/src/game_catalog.rs
index 6449fc5..a93d05e 100644
--- a/app/desktop-ui/src-tauri/src/game_catalog.rs
+++ b/app/desktop-ui/src-tauri/src/game_catalog.rs
@@ -6,12 +6,7 @@ use std::collections::BTreeMap;
 use std::path::PathBuf;
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
-// Discord is only ever used to enrich the display (name/icon/cover) of a game
-// the C++ recorder's local heuristic already detected - never to decide which
-// process is active. All reads used by the clip grid go through
-// resolve_artwork_cached (below), which never makes a network call; artwork
-// is populated/refreshed only by the scheduled background job in main.rs
-// (see refresh_stale) and by the live "currently playing" titlebar lookup.
+// Detection uses the local game-list database; Discord supplies display artwork only.
 
 const DISCORD_FETCH_TIMEOUT: Duration = Duration::from_secs(3);
 
@@ -170,13 +165,7 @@ pub fn resolve_icon(process_name: &str) -> Option<String> {
     entry_by_process(process_name).and_then(|entry| entry.icon_url)
 }
 
-// Executable icons (PNG bytes extracted via SHDefExtractIconW, see exe_icon.rs)
-// are cached here by process name rather than by install path, so the same
-// game keeps its icon across reinstalls/relocations/different machines
-// instead of re-extracting (and never sharing a cache entry) every time the
-// exe's on-disk path differs. Reuses the same table as Discord artwork: an
-// exe icon and Discord artwork for the same process name are just two
-// columns of the one row keyed by process_name_lower.
+// Cache executable icons by normalized process name rather than installation path.
 pub fn cached_exe_icon(process_name: &str) -> Option<Vec<u8>> {
     let key = process_name.to_lowercase();
     let conn = open(true)?;
@@ -263,9 +252,7 @@ impl CatalogEntry {
     }
 }
 
-// Network-capable lookup: fetches from Discord (with an explicit timeout) when
-// the cache is missing or incomplete. Used only by explicit/live contexts
-// (the titlebar's "currently playing" indicator), never by the clip grid.
+// Network-capable artwork lookup for live/explicit requests; exclude the clip grid.
 pub fn resolve_artwork(app_id: Option<&str>, process_name: Option<&str>) -> CatalogEntry {
     if let Some(app_id) = app_id.filter(|id| !id.is_empty()) {
         if let Some(entry) = entry_by_app_id(app_id) {
@@ -364,10 +351,7 @@ fn fetch_and_cache_discord_app(app_id: &str, process_name: Option<&str>) -> Opti
     })
 }
 
-// Background refresh: re-fetches any catalog row with a known discord_app_id
-// whose last_updated is older than max_age (or never set), so the clip grid's
-// cache-only reads (resolve_artwork_cached) stay reasonably fresh without ever
-// blocking a display path on the network. Call from a background thread.
+// Refresh stale artwork on a background worker.
 pub fn refresh_stale(max_age: Duration) {
     let Some(conn) = open(false) else { return };
     if let Err(err) = ensure_schema(&conn) {
diff --git a/app/desktop-ui/src-tauri/src/main.rs b/app/desktop-ui/src-tauri/src/main.rs
index b90b94a..56bb70c 100644
--- a/app/desktop-ui/src-tauri/src/main.rs
+++ b/app/desktop-ui/src-tauri/src/main.rs
@@ -1,10 +1,4 @@
-// Monolith Desktop UI host (Tauri v2 / WebView2). The window loads the bundled
-// Preact frontend directly (native Tauri IPC: invoke/commands/events/asset
-// protocol) instead of navigating to a local loopback HTTP server. The engine
-// (Monolith.exe) is a separate process, reached only over JSON-RPC on
-// 127.0.0.1:45991 for clip mutations / settings reload / recorder control
-// (engine_rpc.rs) - that transport is unchanged and also used by the Stream
-// Deck plugin. See docs/DECISIONS.md (ADR superseding ADR-0011/0012).
+// Tauri hosts bundled frontend assets and the native command/event bridge.
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
 mod asset_scope;
@@ -22,9 +16,7 @@ use std::thread;
 use std::time::Duration;
 use tauri::{Emitter, WebviewUrl, WebviewWindowBuilder};
 
-// Polls the engine's clip-generation counter and emits a `clips` event to the
-// frontend whenever it changes (a clip was saved/stopped). Mirrors the old SSE
-// stream but over a native Tauri event; cheap for a single local user.
+// Emit clips events when the engine generation counter changes.
 fn spawn_clip_watch(app: tauri::AppHandle) {
     thread::spawn(move || {
         let mut last = engine_rpc::clip_generation();
@@ -40,11 +32,7 @@ fn spawn_clip_watch(app: tauri::AppHandle) {
     });
 }
 
-// Discord artwork cache refresh: the clip grid only ever reads
-// game_catalog.db locally (resolve_artwork_cached), so any entry with a known
-// discord_app_id gets re-fetched here in the background on a 72h cadence
-// instead of on the display path. Runs once at startup, then re-checks every
-// 6h so a long-running session doesn't need a restart to pick up refreshes.
+// Refresh artwork in the background; the grid reads only cached rows.
 fn spawn_artwork_refresh() {
     thread::spawn(|| {
         const REFRESH_AGE: Duration = Duration::from_secs(72 * 3600);
diff --git a/app/desktop-ui/src-tauri/src/settings_store.rs b/app/desktop-ui/src-tauri/src/settings_store.rs
index 9cdc4c1..e186e9d 100644
--- a/app/desktop-ui/src-tauri/src/settings_store.rs
+++ b/app/desktop-ui/src-tauri/src/settings_store.rs
@@ -78,11 +78,7 @@ pub fn read_runtime_status() -> Value {
         .unwrap_or_else(|| Value::Object(Map::new()))
 }
 
-// output_dirs() is on the hot path of every catalog command (db_path +
-// media_folder each call it). Reading settings.db + parsing the full JSON
-// each time showed up with large libraries, so cache the result keyed by the
-// settings.db mtime+size - a stat() instead of a DB round-trip, and still
-// correct when the engine (or anything else) rewrites the file.
+// Fingerprint both SQLite files because WAL writes may leave the database timestamp unchanged.
 struct DirCache {
     path: PathBuf,
     stamps: [(Option<SystemTime>, u64); 2],
diff --git a/app/desktop-ui/ui/src/app.tsx b/app/desktop-ui/ui/src/app.tsx
index 896e317..5469789 100644
--- a/app/desktop-ui/ui/src/app.tsx
+++ b/app/desktop-ui/ui/src/app.tsx
@@ -107,8 +107,7 @@ export function App() {
     return () => document.removeEventListener("contextmenu", block);
   }, []);
 
-  // Stable callbacks: ClipCard is memoized, so inline closures here would
-  // re-render the whole grid on every unrelated state change.
+  // Keep callbacks stable for memoized cards.
   const openMenu = useCallback((e: MouseEvent, clip: Clip) => {
     setMenu({ x: e.clientX, y: e.clientY, clip });
   }, []);
diff --git a/app/desktop-ui/ui/src/home/clip-card.tsx b/app/desktop-ui/ui/src/home/clip-card.tsx
index 02af0c2..dbc714d 100644
--- a/app/desktop-ui/ui/src/home/clip-card.tsx
+++ b/app/desktop-ui/ui/src/home/clip-card.tsx
@@ -58,12 +58,7 @@ export const ClipCard = memo(function ClipCard(
     regenTried.current = false;
   }, [clip.id, clip.source, clip.thumbnail_file, clip.duration_seconds]);
 
-  // Icon is always resolved locally: prefer the icon embedded in the game's
-  // own executable (no network, no cache dependency), then fall back to
-  // whatever list_clips already resolved from the local Discord artwork
-  // cache (game_icon_url) - never fetched here, so opening the library never
-  // triggers a network call. A game newly added to the cache picks up its
-  // icon on the next scheduled refresh (see game_catalog::refresh_stale).
+  // Prefer the executable icon, then cached artwork; avoid network lookup per card.
   useEffect(() => {
     let active = true;
     if (!clip.game_executable_path) {
@@ -96,10 +91,7 @@ export const ClipCard = memo(function ClipCard(
       video.load();
     };
 
-    // WebView2 can't decode the default .mkv container, so the <video> canvas
-    // fallback below never fires for most clips. Ask the engine (FFmpeg, decodes
-    // mkv) to regenerate the thumbnail instead; on success it bumps the clip
-    // generation and the grid reloads with the populated thumbnail_file.
+    // Use engine thumbnail generation when WebView2 cannot decode the container.
     const fallbackToEngine = async () => {
       if (cancelled || regenTried.current) return;
       regenTried.current = true;
diff --git a/app/desktop-ui/ui/src/home/confirm-dialog.tsx b/app/desktop-ui/ui/src/home/confirm-dialog.tsx
index ba34443..1f472f8 100644
--- a/app/desktop-ui/ui/src/home/confirm-dialog.tsx
+++ b/app/desktop-ui/ui/src/home/confirm-dialog.tsx
@@ -9,8 +9,6 @@ interface Props {
   onCancel: () => void;
 }
 
-// Custom secondary confirmation popup (deno.md extra #1: delete asks again with
-// a custom popup, not a native dialog).
 export function ConfirmDialog(
   { title, message, confirmLabel = "Confirm", danger, onConfirm, onCancel }: Props,
 ) {
diff --git a/app/desktop-ui/ui/src/home/detail-view.tsx b/app/desktop-ui/ui/src/home/detail-view.tsx
index d2b5ccb..7e5808f 100644
--- a/app/desktop-ui/ui/src/home/detail-view.tsx
+++ b/app/desktop-ui/ui/src/home/detail-view.tsx
@@ -269,8 +269,6 @@ export function DetailView(
     }
   }, [clip?.id, clip?.source]);
 
-  // Bookmarks live in the catalog next to the clip; refresh whenever the clip
-  // changes (replay clips simply have none).
   useEffect(() => {
     let cancelled = false;
     setBookmarks([]);
@@ -283,8 +281,7 @@ export function DetailView(
     return () => { cancelled = true; };
   }, [clip?.id, clip?.source]);
 
-  // Fullscreen reuses this same <video> element in place (see render below) -
-  // only the surrounding chrome/layout changes, so playback never restarts.
+  // Reuse the detail video element when changing fullscreen chrome.
   useEffect(() => {
     if (!fsMode) return;
     appWindow.maximize();
@@ -464,8 +461,7 @@ export function DetailView(
       setDuration(newDuration);
       setCurrent(0);
       setTrimming(false);
-      // The file on disk was replaced in place, so force the player to
-      // re-fetch it (the custom protocol may serve the stale file otherwise).
+      // Reload the source after an in-place trim to discard protocol/decoder caches.
       const v = videoRef.current;
       if (v) {
         v.pause();
diff --git a/app/desktop-ui/ui/src/home/filter-menu.tsx b/app/desktop-ui/ui/src/home/filter-menu.tsx
index 62202c5..49cd34e 100644
--- a/app/desktop-ui/ui/src/home/filter-menu.tsx
+++ b/app/desktop-ui/ui/src/home/filter-menu.tsx
@@ -12,9 +12,6 @@ interface Props {
   format?: (o: string) => string; // display transform (e.g. "#" + tag)
 }
 
-// White-icon filter trigger that opens a custom dropdown: a type-to-search box
-// plus the filterable option list. Replaces the native <select> so games and
-// hashtags can be searched, not just scrolled.
 export function FilterMenu(
   { icon, title, placeholder, allLabel, options, value, onChange, format }: Props,
 ) {
diff --git a/app/desktop-ui/ui/src/home/fullscreen.tsx b/app/desktop-ui/ui/src/home/fullscreen.tsx
index 6e5f9e4..5a447c8 100644
--- a/app/desktop-ui/ui/src/home/fullscreen.tsx
+++ b/app/desktop-ui/ui/src/home/fullscreen.tsx
@@ -20,10 +20,7 @@ function fmtTime(seconds: number): string {
   return `${m}:${s < 10 ? "0" : ""}${s}`;
 }
 
-// Custom YouTube-style fullscreen chrome (not the native <video controls>),
-// driven by an externally-owned <video> element rather than one it renders
-// itself - this lets a caller that already has a playing element (e.g. the
-// detail view) reuse it in place instead of restarting playback on a new one.
+// The video element belongs to the caller; this component owns only its controls.
 export function FullscreenChrome(
   { videoEl, multitrack, onClose }: {
     videoEl: HTMLVideoElement | null;
@@ -124,9 +121,7 @@ export function FullscreenChrome(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [onClose, videoEl, muted]);
 
-  // Document-level (not a wrapping div's onMouseMove) so the autohide timer
-  // resets no matter which sibling element the pointer is over - the chrome
-  // here only renders fixed-position overlays, not a full-viewport container.
+  // Listen on document because the controls are separate fixed-position overlays.
   useEffect(() => {
     document.addEventListener("mousemove", wake);
     return () => document.removeEventListener("mousemove", wake);
@@ -197,12 +192,7 @@ interface FullscreenProps {
   onClose: () => void;
 }
 
-// Fullscreen playback at original framerate, in a custom YouTube-style frame.
-// The window is maximized for the duration of playback and restored on close.
-// Owns its own <video> since there is no existing playing element to reuse
-// (triggered from a card hover-preview, a different element/component); seeds
-// currentTime from the preview's position so it continues near where the
-// preview left off instead of visibly restarting from 0.
+// Seed playback from the card preview position.
 export function Fullscreen({ clip, initialTime = 0, onClose }: FullscreenProps) {
   const [videoEl, setVideoEl] = useState<HTMLVideoElement | null>(null);
 
diff --git a/app/desktop-ui/ui/src/lib/api.ts b/app/desktop-ui/ui/src/lib/api.ts
index 8e67263..39be862 100644
--- a/app/desktop-ui/ui/src/lib/api.ts
+++ b/app/desktop-ui/ui/src/lib/api.ts
@@ -1,5 +1,3 @@
-// Frontend API client. Talks to the Rust host over native Tauri IPC
-// (invoke/listen) instead of the old loopback HTTP server.
 
 import { convertFileSrc, invoke } from "@tauri-apps/api/core";
 import { listen } from "@tauri-apps/api/event";
@@ -56,8 +54,7 @@ export async function fetchHashtags(): Promise<string[]> {
   return invoke<string[]>("distinct_hashtags");
 }
 
-// Wraps a command invocation in the old { ok, error } envelope so call sites
-// (built around fetch()'s always-resolves shape) don't need to change.
+// Normalize command failures into the shared ok/error envelope.
 async function ok(promise: Promise<unknown>): Promise<{ ok: boolean; error?: string }> {
   try {
     await promise;
@@ -144,9 +141,6 @@ export const collectionsApi = {
     ok(invoke("remove_clip_from_collection", { collectionId: id, source: c.source, clipId: c.id })),
 };
 
-// Subscribes to live clip-list changes via a native Tauri event. Calls
-// `onChange` whenever the engine reports a new clip. Returns an unsubscribe
-// function.
 export function subscribeClips(onChange: () => void): () => void {
   let unlisten: (() => void) | null = null;
   let cancelled = false;
@@ -228,15 +222,11 @@ export function setSelectedGame(exe: string): Promise<{ ok: boolean; error?: str
   return ok(invoke("set_selected_game", { exe, pid: null }));
 }
 
-// Native icon extracted from an executable, as a base64 data: URL (null when
-// the file has no icon). Preferred over remote artwork for status backgrounds.
-// `processName` is the cache key on the Rust side (survives reinstalls/path
-// changes); pass "" when unknown (skips caching for that one lookup).
+// Use processName as the persistent icon cache key; an empty key disables caching.
 const exeIconRequests = new Map<string, Promise<string | null>>();
 
 export function exeIconUrl(executablePath: string, processName: string): Promise<string | null> {
-  // Every card of the same game used to issue its own IPC round-trip (with a
-  // base64 PNG payload each); share one promise per process/path instead.
+  // Share one icon request per process/path across cards.
   const key = `${processName}\u0000${executablePath}`;
   let request = exeIconRequests.get(key);
   if (!request) {
diff --git a/app/desktop-ui/ui/src/lib/format.ts b/app/desktop-ui/ui/src/lib/format.ts
index e8f9204..0d3162a 100644
--- a/app/desktop-ui/ui/src/lib/format.ts
+++ b/app/desktop-ui/ui/src/lib/format.ts
@@ -1,4 +1,3 @@
-// Display formatting helpers (deno.md §2.1).
 
 export function formatSize(bytes: number): string {
   if (!bytes || bytes <= 0) return "-";
@@ -13,10 +12,6 @@ export function formatSize(bytes: number): string {
   return `${v.toFixed(1)} ${units[i]}`;
 }
 
-// Human-friendly application label from a raw process name. Raw executable
-// names ("RocketLeague.exe") are never shown in the UI; when no catalog
-// display name exists this derives one: strip the extension, split camelCase /
-// separators, and title-case the words.
 export function prettyAppName(processName?: string | null): string {
   if (!processName) return "Desktop";
   const stem = processName.replace(/\.[^./\\]+$/, "").split(/[/\\]/).pop() ?? "";
@@ -31,20 +26,13 @@ export function prettyAppName(processName?: string | null): string {
   return words.join(" ") || "Desktop";
 }
 
-// Resolves the label to show for an application: the catalog/engine display
-// name when it's a real name, otherwise a prettified process name. Engine
-// display names sometimes fall back to the raw executable ("chrome.exe"),
-// which must never reach the UI.
 export function appLabel(displayName?: string | null, processName?: string | null): string {
   const name = (displayName ?? "").trim();
   if (name && !/\.exe$/i.test(name)) return name;
   return prettyAppName(name || processName);
 }
 
-// Same as appLabel, but for clips specifically: when no game was detected,
-// the label depends on how the clip was captured rather than falling back to
-// the generic "Desktop" - a manual recording with no game is a screen
-// recording, while a replay-buffer save with no game genuinely has none.
+// Without a game, manual clips are screen recordings; replay clips have no game label.
 export function clipSourceLabel(
   clip: { source: "replay" | "manual"; game_display_name?: string | null; game_process_name?: string | null },
 ): string {
@@ -83,8 +71,6 @@ export function formatDate(iso: string): string {
   return `${month} ${d.getDate()}, ${d.getFullYear()} ${time}`;
 }
 
-// Windows device paths ("\\.\DISPLAY2") are never user-facing copy - derive
-// a friendly "Display N" label from the trailing device number instead.
 export function monitorDisplayName(
   mon: { device?: string | null },
   index: number,
diff --git a/app/desktop-ui/ui/src/lib/multitrack.ts b/app/desktop-ui/ui/src/lib/multitrack.ts
index 0245c53..871e8e4 100644
--- a/app/desktop-ui/ui/src/lib/multitrack.ts
+++ b/app/desktop-ui/ui/src/lib/multitrack.ts
@@ -1,20 +1,5 @@
-// Simultaneous multi-track audio playback (deno.md §2.1 successor).
-//
-// Monolith records separate audio streams (game, mic, apps) into one file
-// (see libs/encoding/mux_common.cpp). Chromium/WebView2 exposes every track
-// via `video.audioTracks`, but a single <video>/<audio> element only ever
-// *renders* one enabled track at a time - flipping `audioTracks[i].enabled`
-// for more than one track has no effect on what you hear. The only way to
-// hear every track at once is to decode each extra track on its own hidden
-// element and let the OS mixer combine them acoustically, so this hook spins
-// up one shadow <video> per extra track and keeps it in lockstep with the
-// visible primary element (play/pause, seek, mute, volume, rate).
-//
-// Sync is event-driven (play/pause/seeking mirrored immediately, currentTime
-// drift corrected on timeupdate), not sample-accurate - under heavy CPU
-// contention drift beyond ~150ms is possible before the next correction
-// tick. That's an accepted tradeoff: still strictly better than silently
-// dropping every track but the first.
+// WebView2 plays the first audio track. Hidden elements select additional tracks
+// by fragment and follow the visible video clock; unavailable tracks are ignored.
 
 import { useEffect, useRef } from "preact/hooks";
 
@@ -29,10 +14,7 @@ export interface MultiTrackHandle {
   setVolume: (volume: number) => void;
 }
 
-// Attaches shadow tracks for `video`'s extra audio tracks once metadata is
-// available. `src` must match the primary element's current src. Returns a
-// handle whose setMuted/setVolume must be used instead of touching the
-// primary element's `.muted`/`.volume` directly, so shadows stay in lockstep.
+// Attach extra audio elements after metadata is available; cleanup releases them.
 export function useMultiTrackAudio(
   video: HTMLVideoElement | null,
   src: string | null,
diff --git a/app/desktop-ui/ui/src/lib/player.ts b/app/desktop-ui/ui/src/lib/player.ts
index 804517c..a6af007 100644
--- a/app/desktop-ui/ui/src/lib/player.ts
+++ b/app/desktop-ui/ui/src/lib/player.ts
@@ -1,9 +1,7 @@
 // Video player helpers shared by the card preview and the detail player.
 // See multitrack.ts for simultaneous multi-track audio playback.
 
-// Fully resets a <video> element's audio/playback state before it is reused for
-// a different clip, so leftover audio from the previous clip can't bleed through
-// during the first silent seconds of the next one.
+// Clear the old source before reusing an element for another clip.
 export function resetPlayer(video: HTMLVideoElement | null): void {
   if (!video) return;
   video.pause();
@@ -13,7 +11,6 @@ export function resetPlayer(video: HTMLVideoElement | null): void {
   } catch {
     /* not seekable yet */
   }
-  // Detach the source and reload so decoder/audio state is cleared.
   video.removeAttribute("src");
   try {
     video.load();
diff --git a/app/desktop-ui/ui/src/lib/settings-api.ts b/app/desktop-ui/ui/src/lib/settings-api.ts
index 8339684..a2749bb 100644
--- a/app/desktop-ui/ui/src/lib/settings-api.ts
+++ b/app/desktop-ui/ui/src/lib/settings-api.ts
@@ -24,9 +24,7 @@ export async function saveConfig(config: Config): Promise<{ ok: boolean; error?:
   }
 }
 
-// Runtime capabilities (available encoders, monitors, input devices) published
-// by the engine to runtime-status.json. Read-only; used to capability-gate the
-// UI (never offer an encoder/monitor the machine can't do). Best-effort.
+// Engine capabilities are best-effort snapshots from runtime-status.json.
 export interface RuntimeStatus {
   available_encoders?: string[];
   active_encoder?: string;
diff --git a/app/desktop-ui/ui/src/settings/audio-settings.tsx b/app/desktop-ui/ui/src/settings/audio-settings.tsx
index 457330b..b2eccf2 100644
--- a/app/desktop-ui/ui/src/settings/audio-settings.tsx
+++ b/app/desktop-ui/ui/src/settings/audio-settings.tsx
@@ -21,11 +21,7 @@ interface Source {
   tracks: number[];
 }
 
-// Audio capture is modelled as a flat list of sources, each with its own
-// enable + volume that the recorder actually applies to the mix. The UI groups
-// them into Game Audio (desktop), Microphone (input), and any other apps that
-// currently have audio. Editing anything switches audio.mode to "custom" so the
-// engine honours the explicit source list.
+// Editing sources selects custom mode; keep desktop and microphone baseline entries.
 export function AudioSettings({ cfg, rs, update }: Props) {
   const audio = cfg.audio ?? {};
   const sources: Source[] = Array.isArray(audio.sources) ? audio.sources : [];
@@ -36,9 +32,7 @@ export function AudioSettings({ cfg, rs, update }: Props) {
   const game = find((s) => s.type === "desktop");
   const mic = find((s) => s.type === "input");
 
-  // Custom mode uses the explicit source list, so it must always contain the two
-  // baseline sources (Game Audio → track 1, Microphone → track 2) that the
-  // default mode implies - otherwise editing one would silently drop the other.
+  // Custom source lists must include the implicit desktop/microphone defaults.
   const withBaseline = (list: Source[]): Source[] => {
     const out = list.slice();
     if (!out.some((s) => s.type === "desktop")) {
@@ -58,7 +52,6 @@ export function AudioSettings({ cfg, rs, update }: Props) {
     return out;
   };
 
-  // Rewrites the whole source list and forces custom mode so the engine applies it.
   const commit = (next: Source[]) => {
     update("audio.mode", "custom");
     update("audio.sources", withBaseline(next));
@@ -97,12 +90,7 @@ export function AudioSettings({ cfg, rs, update }: Props) {
   const processFor = (procName: string): Source | undefined =>
     find((s) => s.type === "process" && s.process_name?.toLowerCase() === procName.toLowerCase());
 
-  // Track layout: the microphone always gets its own track (track 2) - that's
-  // never up for debate since a mixed-in mic can't be un-mixed later. Every
-  // *other* audio source (game desktop audio + each other app) either all
-  // share the game's track (single track) or each gets its own free track
-  // (separate tracks, tracks 1/3/4/5/6). Defaults to "separate" to match the
-  // behaviour this UI shipped with before the toggle existed.
+  // Reserve track 2 for the microphone; other sources share track 1 or use 3..6.
   const trackLayout: "single" | "separate" = audio.track_layout === "single" ? "single" : "separate";
 
   const nextFreeTrack = (): number => {
diff --git a/app/desktop-ui/ui/src/settings/controls.tsx b/app/desktop-ui/ui/src/settings/controls.tsx
index 726ca24..fd364e9 100644
--- a/app/desktop-ui/ui/src/settings/controls.tsx
+++ b/app/desktop-ui/ui/src/settings/controls.tsx
@@ -3,7 +3,6 @@ import { useEffect, useRef, useState } from "preact/hooks";
 import { Icon } from "../shell/icons.tsx";
 import { pickFolder } from "../lib/settings-api.ts";
 
-// ── Layout primitives ──────────────────────────────────────────────────────────
 // A settings page is a stack of Sections; each Section is a titled card holding
 // a set of Fields. This gives every group a consistent frame, divider and rhythm.
 
@@ -46,7 +45,6 @@ export function Field(
   );
 }
 
-// ── Controls ────────────────────────────────────────────────────────────────────
 
 export function Toggle(
   { checked, onChange }: { checked: boolean; onChange: (v: boolean) => void },
@@ -113,8 +111,6 @@ export function TextInput(
   );
 }
 
-// Read-only path field with a Browse button that opens the native Windows folder
-// picker. The user never types a path manually.
 export function FolderPicker(
   { value, onPick }: { value: string; onPick: (path: string) => void },
 ) {
@@ -188,10 +184,6 @@ export function VolumeSlider(
   );
 }
 
-// ── Hotkey capture ──────────────────────────────────────────────────────────────
-// Replaces free-text hotkey entry. On focus it listens for a real key chord and
-// writes the canonical "Ctrl+Alt+3" string, so combinations the old text box
-// dropped (e.g. Ctrl+Alt+3) are captured correctly.
 
 const MOD_LABEL: Record<string, string> = {
   Control: "Ctrl",
diff --git a/app/desktop-ui/ui/src/settings/settings-popup.tsx b/app/desktop-ui/ui/src/settings/settings-popup.tsx
index 5eb85c9..e7b877b 100644
--- a/app/desktop-ui/ui/src/settings/settings-popup.tsx
+++ b/app/desktop-ui/ui/src/settings/settings-popup.tsx
@@ -26,9 +26,6 @@ type Page =
   | "advanced"
   | "game";
 
-// Grouped so the nav reads as sections (like Windows Settings), not a flat
-// list - each group heading is real structure (recording pipeline vs. where
-// files land vs. power-user knobs), not decoration.
 const PAGE_GROUPS: { label: string; pages: { id: Page; label: string; icon: string }[] }[] = [
   {
     label: "Recording",
@@ -55,8 +52,7 @@ const PAGE_GROUPS: { label: string; pages: { id: Page; label: string; icon: stri
   },
 ];
 
-// Bitrate presets (Mbps). The heaviest two are flagged so the UI can warn about
-// disk usage.
+// Bitrate presets are in Mbps.
 const BITRATE_PRESETS = [3, 5, 7, 10, 15, 20, 25, 30, 35, 40, 50, 70, 100];
 const FPS_PRESETS = [24, 30, 60, 120, 144];
 const REPLAY_PRESETS = [15, 30, 60, 120];
@@ -83,10 +79,6 @@ function setPath(obj: any, path: string, value: any): any {
   return copy;
 }
 
-// Maps a concrete FFmpeg encoder name to a human-readable vendor + codec, so the
-// UI can show "NVIDIA NVENC · H.265" instead of a bare codec that hides whether
-// encoding runs in software (x264/OpenH264) or on which GPU vendor. Covers both
-// the current in-process encoder set and the post-refactor names.
 function encoderLabel(
   raw: string | undefined,
 ): { vendor: string; codec: string; kind: "hw" | "sw" } | null {
@@ -164,10 +156,7 @@ export function SettingsPopup({ onClose }: Props) {
     })();
   }, []);
 
-  // Runtime status (audio sessions, active game, devices, monitors) is a live
-  // snapshot the engine keeps refreshing on its own cadence - re-poll it while
-  // the popup is open so e.g. "Other sources" reflects apps that start/stop
-  // playing audio without the user having to close and reopen Settings.
+  // Poll capabilities while Settings is open to reflect new devices and audio sessions.
   useEffect(() => {
     const timer = setInterval(async () => {
       setRs(await getRuntimeStatus());
@@ -262,9 +251,7 @@ export function SettingsPopup({ onClose }: Props) {
   );
 }
 
-// Replay duration: a preset dropdown (15/30/60/120) plus Custom, which enables a
-// number field. Custom mode is tracked locally so it stays selected even when the
-// custom value happens to equal a preset number.
+// Track custom mode separately even when its value equals a preset.
 function ReplayDurationSection(
   { value, onChange }: { value: number; onChange: (v: number) => void },
 ) {
diff --git a/app/desktop-ui/ui/src/shell/titlebar.tsx b/app/desktop-ui/ui/src/shell/titlebar.tsx
index cca8744..6a7e039 100644
--- a/app/desktop-ui/ui/src/shell/titlebar.tsx
+++ b/app/desktop-ui/ui/src/shell/titlebar.tsx
@@ -35,7 +35,6 @@ export function Titlebar({ view }: Props) {
   const saving = useRef(false);
   const [saveError, setSaveError] = useState<string | null>(null);
 
-  // Runtime + engine status are read-only and safe to poll live.
   useEffect(() => {
     let alive = true;
     const load = async () => {
@@ -61,10 +60,7 @@ export function Titlebar({ view }: Props) {
     };
   }, []);
 
-  // Config is loaded once, then refreshed only when the capture popover opens.
-  // It is deliberately NOT polled: the titlebar itself is the writer, so a
-  // periodic re-fetch would race the optimistic toggle and revert it a beat
-  // later (the "sets then flips back" bug).
+  // Refresh config on open rather than polling over optimistic edits.
   useEffect(() => {
     let alive = true;
     getConfig().then((cfg) => {
@@ -109,9 +105,6 @@ export function Titlebar({ view }: Props) {
   const activeGame = runtime.active_game;
   const gameProcess = activeGame?.process_id ? activeGame.process_name : "";
   const exePath = activeGame?.process_id ? (activeGame.executable_path ?? "") : "";
-  // Detected games are DB-gated, so display_name is always the game-list name
-  // (e.g. "AURA Gamers gioco") - show it verbatim, no prettify transform. Only
-  // fall back to appLabel for the rare case the engine emits a raw exe name.
   useEffect(() => {
     let alive = true;
     if (!gameProcess) {
@@ -154,9 +147,6 @@ export function Titlebar({ view }: Props) {
   const recording = !!engine.recording;
   const clipping = !recording && !!engine.replay_enabled;
   const statusLabel = !connected ? "Disconnected" : recording ? "Recording" : clipping ? "Clipping" : "Idle";
-  // active_game is an object; render its label, never the object itself (doing so
-  // makes Preact treat it as a vnode → "Objects are not valid as a child" + a
-  // re-render loop that hangs the whole app).
   const gameLabel = activeGame?.process_id
     ? appLabel(activeGame.display_name, activeGame.process_name)
     : "";
diff --git a/app/desktop-ui/ui/styles.css b/app/desktop-ui/ui/styles.css
index 5813f46..bd3ccde 100644
--- a/app/desktop-ui/ui/styles.css
+++ b/app/desktop-ui/ui/styles.css
@@ -79,7 +79,6 @@ body {
 }
 ::-webkit-scrollbar-thumb:hover { background: var(--light-hi); }
 
-/* ── App frame ───────────────────────────────────────────────────────────── */
 .win {
   height: 100vh;
   display: flex;
@@ -88,7 +87,6 @@ body {
   overflow: hidden;
 }
 
-/* ── Custom title bar ────────────────────────────────────────────────────── */
 .titlebar {
   height: 50px;
   flex: none;
@@ -172,7 +170,7 @@ body {
 .tb-status {
   position: relative;
   margin-left: 14px;
-  /* Fill the bar's full height; only the width is constrained below. */
+
   align-self: stretch;
   display: grid;
   grid-auto-flow: column;
@@ -183,7 +181,7 @@ body {
   display: flex;
   align-items: center;
   gap: 10px;
-  /* Fill the bar vertically (text stays centered); only the width is limited. */
+
   height: 100%;
   padding: 0 20px;
   background: none;
@@ -227,7 +225,7 @@ body {
   background-image: inherit;
   background-repeat: repeat;
   background-position: center;
-  /* Tile scaled from 40px (3 angled rows) to 24px so 5 rows fit (40 * 3/5). */
+
   background-size: 32px 32px;
   transform: rotate(-35deg);
 }
@@ -235,7 +233,7 @@ body {
   opacity: 1;
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='34' height='26' viewBox='0 0 34 26'%3E%3Cg fill='none' stroke='rgba(255,255,255,.16)' stroke-width='1.2'%3E%3Crect x='7' y='4' width='20' height='14' rx='2'/%3E%3Cpath d='M14 22h6M17 18v4'/%3E%3C/g%3E%3C/svg%3E");
 }
-/* Same 3->5 row scale (34*3/5, 26*3/5), keeping the tile's proportions. */
+
 .capture-feed.screen .feed-bg::before { background-size: 20.4px 15.6px; }
 .feed-shade { background: linear-gradient(180deg, rgba(7, 7, 7, .35), rgba(7, 7, 7, .72)); }
 .capture-feed:hover .feed-bg { opacity: .55; }
@@ -380,7 +378,6 @@ body {
 .monitor-name { font-size: 12px; }
 .monitor-size { margin-top: 2px; font-family: var(--mono); font-size: 10.5px; color: var(--text-faint); }
 
-/* ── Shell: sidebar + content ────────────────────────────────────────────── */
 .shell {
   flex: 1;
   display: flex;
@@ -432,7 +429,6 @@ body {
 .side-item.active.fav-active::before { background: #f5c542; }
 .side-spacer { flex: 1; }
 
-/* Content is its own scroll panel - a dark well inset into the medium chrome */
 .content {
   flex: 1;
   min-width: 0;
@@ -442,7 +438,6 @@ body {
   padding: 0 26px 36px;
 }
 
-/* ── Content toolbar ─────────────────────────────────────────────────────── */
 .toolbar {
   display: flex;
   gap: 12px;
@@ -461,7 +456,7 @@ body {
 
 .search-wrap {
   position: relative;
-  /* Small, anchored to the right (filters live on the left). */
+
   flex: 0 0 auto;
   width: 240px;
 }
@@ -487,7 +482,6 @@ body {
   padding-bottom: 0;
 }
 
-/* ── Icon filter menus (game / hashtag) with searchable dropdown ──────────── */
 .filter-menus { display: flex; align-items: center; gap: 8px; }
 .filter-menu { position: relative; }
 .filter-btn {
@@ -506,7 +500,7 @@ body {
 .filter-btn:hover { background: var(--light); }
 .filter-btn.active { background: var(--accent-soft); color: var(--accent-hi); }
 .filter-btn > svg { width: 18px; height: 18px; }
-/* Dropdown affordance: a small caret that flips when the menu is open. */
+
 .filter-caret {
   display: grid;
   place-items: center;
@@ -609,7 +603,6 @@ body {
 .btn-toggle { display: inline-flex; align-items: center; gap: 7px; }
 .btn-toggle.on { background: var(--accent); border-color: var(--accent); color: var(--accent-ink); }
 
-/* ── Grid header ─────────────────────────────────────────────────────────── */
 .grid-head { display: flex; align-items: center; gap: 12px; padding: 8px 2px 18px; }
 .grid-count {
   font-family: var(--mono);
@@ -621,7 +614,6 @@ body {
 .grid-count b { color: var(--text); font-weight: 700; }
 .grid-head .rule { flex: 1; height: 1px; background: linear-gradient(90deg, var(--line), transparent); }
 
-/* ── Grid + cards ────────────────────────────────────────────────────────── */
 .grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(268px, 1fr));
@@ -778,7 +770,6 @@ body {
   white-space: nowrap;
 }
 
-/* ── Empty / loading ─────────────────────────────────────────────────────── */
 .empty {
   color: var(--text-dim);
   padding: 92px 40px;
@@ -804,7 +795,6 @@ body {
 .loading-dots i:nth-child(3) { animation-delay: .3s; }
 @keyframes load-b { 0%,100% { opacity: .25; transform: translateY(0); } 50% { opacity: 1; transform: translateY(-4px); } }
 
-/* ── Context menu ────────────────────────────────────────────────────────── */
 .ctx-menu {
   position: fixed;
   min-width: 196px;
@@ -837,7 +827,6 @@ body {
 .ctx-danger { color: var(--danger); }
 .ctx-danger:hover { background: rgba(229, 84, 75, .16); }
 
-/* ── Modals ──────────────────────────────────────────────────────────────── */
 .modal-backdrop {
   position: fixed; inset: 0;
   background: rgba(0, 0, 0, .62);
@@ -871,7 +860,6 @@ body {
 .tag-add .input { flex: 1; }
 .muted { color: var(--text-dim); font-size: 13px; }
 
-/* ── Fullscreen ──────────────────────────────────────────────────────────── */
 .fs-backdrop {
   position: fixed; inset: 0;
   background: #000;
@@ -919,7 +907,6 @@ body {
 }
 .fs-btn:hover { background: rgba(255,255,255,.14); }
 
-/* ── Detail view ─────────────────────────────────────────────────────────── */
 .detail-backdrop {
   position: fixed; inset: 0;
   background: rgba(0, 0, 0, .72);
@@ -1115,7 +1102,6 @@ body {
 }
 .tag-suggestions button:hover { background: var(--light); color: var(--text); }
 
-/* ── Settings popup ──────────────────────────────────────────────────────── */
 .settings {
   position: relative;
   display: grid;
@@ -1203,7 +1189,6 @@ body {
 
 .settings-body { padding: 24px 26px; overflow-y: auto; }
 
-/* Auto-save status, bottom of the settings rail (replaces the old Save footer) */
 .save-status {
   display: flex;
   align-items: center;
@@ -1247,7 +1232,6 @@ body {
 .audio-name { flex: 1; min-width: 0; font-size: 13px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .audio-vol { font-family: var(--mono); font-size: 12px; color: var(--text-dim); width: 40px; text-align: right; }
 
-/* ── Hover-preview fade (no black flash) ─────────────────────────────────── */
 .card-video {
   position: absolute;
   inset: 0;
@@ -1266,7 +1250,6 @@ body {
 .game-icon.placeholder svg { width: 13px; height: 13px; }
 .fav-badge svg, .ov-btn svg, .ctx-ico svg { display: block; }
 
-/* ── Detail view: title + filename ──────────────────────────────────────── */
 .detail-filename {
   font-family: var(--mono);
   font-size: 11px;
@@ -1275,7 +1258,6 @@ body {
   margin-top: -10px;
 }
 
-/* ── Settings: sections + cards ─────────────────────────────────────────── */
 .set-section { margin-bottom: 26px; }
 .set-section:last-child { margin-bottom: 4px; }
 .set-section-head { margin-bottom: 12px; padding: 0 2px; }
@@ -1326,7 +1308,6 @@ body {
 .set-empty-row { padding: 2px 0; }
 .opt-danger { color: #e5776e; }
 
-/* ── Toggle switch ──────────────────────────────────────────────────────── */
 .toggle {
   width: 42px; height: 24px;
   flex: none;
@@ -1350,7 +1331,6 @@ body {
 }
 .toggle.on .toggle-knob { transform: translateX(18px); background: var(--accent-ink); }
 
-/* ── Segmented control ──────────────────────────────────────────────────── */
 .segmented {
   display: inline-flex;
   background: var(--field);
@@ -1375,13 +1355,11 @@ body {
 .seg:hover { color: var(--text); }
 .seg.active { background: var(--accent); color: var(--accent-ink); }
 
-/* ── Folder picker ──────────────────────────────────────────────────────── */
 .folder-picker { display: flex; gap: 8px; align-items: center; min-width: 340px; }
 .folder-path { flex: 1; min-width: 0; font-family: var(--mono); font-size: 12.5px; }
 .btn-ghost { display: inline-flex; align-items: center; gap: 7px; white-space: nowrap; }
 .btn-ghost svg { display: block; }
 
-/* ── Volume slider ──────────────────────────────────────────────────────── */
 .volume { display: flex; align-items: center; gap: 12px; }
 .volume input[type="range"] { width: 140px; accent-color: #fff; cursor: pointer; }
 .volume.disabled { opacity: .4; }
@@ -1394,7 +1372,6 @@ body {
 }
 .audio-other-control { display: flex; align-items: center; gap: 16px; }
 
-/* ── Hotkey capture ─────────────────────────────────────────────────────── */
 .hotkey-capture {
   display: inline-flex;
   align-items: center;
@@ -1419,7 +1396,6 @@ body {
   *, *::before, *::after { animation: none !important; transition: none !important; }
 }
 
-/* ── Bookmarks & trim ────────────────────────────────────────────────────── */
 .detail-bookmarks { margin-top: 18px; }
 .detail-bookmarks-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; }
 .detail-bookmarks-head .k {
@@ -1452,7 +1428,6 @@ body {
 .bm-swatch-btn.active { outline: 2px solid var(--accent); outline-offset: 1px; }
 .bm-label-input { flex: 1; min-width: 0; padding: 6px 9px; font-size: 13px; }
 
-/* Timeline wrapper: bookmark ticks sit on the scrubber line. */
 .timeline-wrap { position: relative; }
 .bm-marker {
   position: absolute;
@@ -1466,7 +1441,6 @@ body {
 }
 .bm-marker:hover { border-color: var(--light-hi); }
 
-/* Trim track: thin line with a start/end handle pair + selection overlay. */
 .trim-track {
   position: relative;
   height: 28px;
@@ -1514,7 +1488,6 @@ body {
 .act-trim.active { color: var(--accent); }
 .act-btn:disabled { opacity: .35; cursor: default; }
 
-/* ── Collections ─────────────────────────────────────────────────────────── */
 .collections-grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(268px, 1fr));
diff --git a/app/desktop-ui/vite.config.ts b/app/desktop-ui/vite.config.ts
index 4b5b2d1..d234ef4 100644
--- a/app/desktop-ui/vite.config.ts
+++ b/app/desktop-ui/vite.config.ts
@@ -9,7 +9,7 @@ export default defineConfig({
     emptyOutDir: true,
     target: "chrome110", // WebView2 is evergreen Edge/Chromium
   },
-  // Fixed port + strictPort so it matches src-tauri/tauri.conf.json's devUrl.
+  // Keep the dev port aligned with tauri.conf.json.
   server: {
     port: 1420,
     strictPort: true,
diff --git a/app/recorder/src/feedback_sounds.h b/app/recorder/src/feedback_sounds.h
index a38658f..518da49 100644
--- a/app/recorder/src/feedback_sounds.h
+++ b/app/recorder/src/feedback_sounds.h
@@ -8,9 +8,7 @@
 #include <cstdint>
 #include <vector>
 
-// Synthesised WAV feedback tones played on record start/stop and clip save.
-// All sounds are sine-wave based with a short attack/decay envelope so they
-// feel intentional rather than system-alert-like.
+// Feedback WAV tones use short sine envelopes.
 namespace feedback {
 
 enum class Sound { RecordStart, RecordStop, ClipSaved };
diff --git a/app/recorder/src/main.cpp b/app/recorder/src/main.cpp
index 9b8bd88..ba17042 100644
--- a/app/recorder/src/main.cpp
+++ b/app/recorder/src/main.cpp
@@ -51,7 +51,6 @@
 #include <thread>
 #include <vector>
 
-// ── Constants ─────────────────────────────────────────────────────────────────
 
 static constexpr WCHAR kWindowClass[] = L"MonolithMsgWnd";
 static constexpr WCHAR kAppName[]     = L"Monolith";
@@ -72,10 +71,6 @@ enum Cmd : UINT {
     CMD_ADD_BOOKMARK    = 1008,
 };
 
-// ── Logging ───────────────────────────────────────────────────────────────────
-// Implementation lives in libs/logging (disabled by default; toggled via
-// Settings > Advanced > advanced.logging_enabled). These are thin wrappers so
-// call sites across this file don't need to change.
 
 static std::wstring known_folder_path(REFKNOWNFOLDERID folder)
 {
@@ -155,8 +150,7 @@ static void log_path(const char* tag, const char* prefix, const std::wstring& pa
     log_msg(tag, msg);
 }
 
-// Always-on error variants (bypass advanced.logging_enabled) - for failures the
-// user must be able to diagnose even without opting into verbose logging.
+// Error logging bypasses the verbose-logging setting.
 static void log_error(const char* tag, const char* msg)
 {
     logging::log_error(tag, msg);
@@ -175,7 +169,6 @@ static void log_error_path(const char* tag, const char* prefix, const std::wstri
 using platform_win::utf8_to_wide;
 using platform_win::wide_to_utf8;
 
-// ── Globals ───────────────────────────────────────────────────────────────────
 
 static bool apps_use_light_theme()
 {
@@ -196,9 +189,7 @@ static void apply_native_window_theme(HWND hwnd)
 {
     BOOL dark = apps_use_light_theme() ? FALSE : TRUE;
 
-    // Resolve the dwmapi/uxtheme entry points once and cache them - this runs on
-    // every tray right-click and theme change, so repeated LoadLibrary/FreeLibrary
-    // would be pure waste.
+    // Cache theme-library handles for the process lifetime.
     using DwmSetWindowAttributeFn = HRESULT (WINAPI*)(HWND, DWORD, LPCVOID, DWORD);
     using SetPreferredAppModeFn   = int (WINAPI*)(int);
     using FlushMenuThemesFn       = void (WINAPI*)();
@@ -211,8 +202,7 @@ static void apply_native_window_theme(HWND hwnd)
             FlushMenuThemesFn       flush_menu      = nullptr;
             SetWindowThemeFn        set_theme       = nullptr;
         } f;
-        // Leaked intentionally for process lifetime - these modules stay loaded
-        // anyway and the handles never need releasing.
+        // The cached modules remain loaded until process exit.
         if (HMODULE dwm = LoadLibraryW(L"dwmapi.dll"))
             f.set_attr = reinterpret_cast<DwmSetWindowAttributeFn>(
                 GetProcAddress(dwm, "DwmSetWindowAttribute"));
@@ -253,15 +243,11 @@ static std::array<encoding::AudioEncoder, 6> g_audio_encoders;
 // their encoder. The mixer's sink forwards summed PCM into that track's encoder.
 static std::array<std::unique_ptr<encoding::TrackMixer>, 7> g_track_mixers;
 
-// One output route for a source: which track, and (when that track is mixed) the
-// source's id within the mixer. mixer_src == -1 means push directly to encoder.
-// gain is the source's linear volume (0.0-1.0), applied to the recorded audio:
-// for mixed tracks it lives in the mixer source; for direct tracks it is applied
-// in-place before push_pcm.
+// mixer_src == -1 routes directly to the encoder. Apply source gain in the
+// mixer or to direct PCM before encoding.
 struct AudioRoute { int track = 0; int mixer_src = -1; float gain = 1.0f; };
 
-// A live capture plus the routes its callback writes to. Routes are kept so that
-// when a capture is removed (e.g. Active Game swap) its mixer slots are released.
+// Retain route IDs to release mixer slots when removing a capture.
 struct ActiveCapture {
     std::unique_ptr<audio::WasapiCapture> capture;
     std::vector<AudioRoute> routes;
@@ -282,7 +268,6 @@ static std::atomic<uint64_t> g_perf_bgra_memcpy_time_us_total{ 0 };
 // Backoff after a failed encoder open: don't re-probe on every captured frame.
 static std::atomic<uint64_t> g_video_enc_retry_after_ms{ 0 };
 static constexpr uint64_t kVideoEncRetryBackoffMs = 2000;
-// ── OBS-style video pacer: fixed-rate thread feeds encoder ──────────────
 static HANDLE               g_pacer_thread       = nullptr;
 static HANDLE               g_pacer_stop_event   = nullptr;
 static std::mutex           g_pacer_mutex;
@@ -307,23 +292,17 @@ static std::string g_recording_container = "mkv";
 static std::atomic<bool> g_replay_enabled{ true };
 static std::atomic<bool> g_recording_enabled{ true };
 
-// Snapshot of the two output folders, guarded so the IPC thread can resolve the
-// right clip DB for UI-driven mutations without racing settings reloads on the
-// UI thread. Updated in apply_runtime_settings().
+// Guard output-folder snapshots across settings reload and IPC mutation threads.
 static std::mutex    g_dirs_mutex;
 static std::wstring  g_clips_dir_snapshot;
 static std::wstring  g_recs_dir_snapshot;
 static settings::Config g_settings;
 
-// Bumped each time a clip is cataloged (replay save or manual stop). Read by the
-// IPC get_status handler so the UI host can push a live clip-list refresh.
+// Catalog generation is polled by the UI host.
 static std::atomic<uint64_t>     g_clip_generation{0};
 
-// ── Recording elapsed-time clock (QPC-based, pause-aware) ────────────────────
-// Used to timestamp bookmarks at the moment they are added. Written on the
-// UI/tray thread (start/pause/resume/stop), read on the IPC thread - all fields
-// are atomics, and a torn read only shifts a bookmark timestamp by a frame or
-// two. Pause spans are accumulated in QPC units and subtracted at read time.
+// Bookmark time is elapsed QPC time minus accumulated pauses. Control writes
+// on the tray thread; IPC reads the atomic fields.
 static std::atomic<int64_t> g_rec_clock_freq{0};
 static std::atomic<int64_t> g_rec_clock_start_qpc{0};
 static std::atomic<int64_t> g_rec_paused_qpc_total{0};
@@ -379,18 +358,13 @@ static void rec_clock_resume()
     }
 }
 
-// Active-game audio source: re-evaluated every poll_interval_ms by a UI-thread timer
-// and also on foreground-window changes (fast scan, rate-limited).
+// Poll active-game audio on the tray thread and on coalesced foreground changes.
 static constexpr UINT_PTR kActiveGameTimerId = 1;
 
-// Replay-buffer memory budget, fixed internally (no UI knob). 512 MB is a safe
-// ceiling for the encoded-packet ring across supported bitrates/durations.
+// Encoded payload cap: allocator and in-flight snapshot memory are additional.
 static constexpr int64_t kReplayMemoryBudgetMb = 512;
 
-// Active-game detection runs on a fixed 3 s cadence. Detection is DB-gated: a
-// process only counts as a game when its executable is in the locally-cached
-// Discord detectable list (see libs/gamelist). Window facts (foreground/
-// fullscreen) only order candidates and pick the capture target, never gate.
+// Detection admits database-matched executables; window facts rank candidates.
 static constexpr int kActiveGamePollMs = 3000;
 
 static std::vector<int>          g_active_game_tracks;
@@ -423,10 +397,7 @@ static std::string now_local_ts()
     return ts;
 }
 
-// Re-writes AppData\Local\Monolith\runtime-status.json from g_runtime_status,
-// but only when the serialized content actually changed - the active-game poll
-// runs every few seconds and on every foreground change, and most ticks produce
-// identical status, so skipping no-op disk writes avoids needless I/O.
+// Skip unchanged runtime-status writes; cache only successful writes.
 static std::string g_last_runtime_status_json;
 static std::mutex  g_last_runtime_status_mutex;
 
@@ -447,10 +418,7 @@ static void publish_runtime_status()
         log_msg("settings", ("runtime-status write failed: " + error).c_str());
 }
 
-// ── OBS-style video pacer ──────────────────────────────────────────────
-// Fixed-rate video thread feeds encoder exactly like OBS video_output.
-// Producer (WGC callback): copies BGRA to g_pacer_shared under mutex.
-// Consumer (pacer thread): reads latest frame each tick, pushes to encoder.
+// The WGC callback publishes BGRA under a mutex; the pacer consumes the latest frame.
 
 static uint64_t qpc_elapsed_us(const LARGE_INTEGER& start,
                                const LARGE_INTEGER& end);
@@ -509,9 +477,7 @@ static DWORD WINAPI pacer_thread_proc(LPVOID)
         nullptr, nullptr,
         CREATE_WAITABLE_TIMER_HIGH_RESOLUTION, TIMER_ALL_ACCESS);
 
-    // One wakeup per frame slot (4 ms floor). The QPC-locked CFR below absorbs
-    // tick jitter with dup/skip, so oversampling the tick 2x only doubles
-    // wakeups (and blocks CPU C-states) without tightening output timing.
+    // Wake once per frame slot, with a 4 ms minimum interval.
     int tick_ms = (g_pacer_fps > 0) ? (1000 / g_pacer_fps) : 4;
     if (tick_ms < 4) tick_ms = 4;
 
@@ -532,11 +498,7 @@ static DWORD WINAPI pacer_thread_proc(LPVOID)
             if (w == WAIT_OBJECT_0 || w == WAIT_FAILED) break;
         }
 
-        // Frozen-frame: when the captured game window is minimized, WGC delivers
-        // no (or degenerate) frames. Deliberately hold the last good frame - the
-        // CFR loop keeps duplicating local_bgra - instead of swapping in whatever
-        // WGC produces while iconic. Applies to both recording and replay since
-        // both consume this pacer -> encoder path.
+        // Hold the last captured frame while the game window is minimized.
         HWND cap_target = g_capture_target_hwnd.load(std::memory_order_relaxed);
         const bool minimized = cap_target && IsIconic(cap_target);
         if (minimized != frozen) {
@@ -545,10 +507,7 @@ static DWORD WINAPI pacer_thread_proc(LPVOID)
                                          : "captured game restored");
         }
 
-        // Pull the latest captured frame (if a new one arrived).  Swap buffers
-        // under the lock instead of copying: the consumer takes ownership of the
-        // shared frame's storage and hands back its own (reused next push), so
-        // there is no per-frame full-frame memcpy on the consumer side.
+        // Swap frame buffers under the mutex; encode outside it.
         if (!minimized) {
             std::lock_guard<std::mutex> lock(g_pacer_mutex);
             if (g_pacer_shared.frame_id != local_last_id) {
@@ -569,10 +528,7 @@ static DWORD WINAPI pacer_thread_proc(LPVOID)
         if (local_bgra.empty())
             continue;
 
-        // ── Clock-locked CFR: emit frames until we've caught up to wall-clock.
-        // target = number of frames that SHOULD exist by now.  Duplicate the
-        // latest frame to fill gaps; this makes playback speed independent of
-        // timer jitter, encode cost, and configured fps.
+        // Derive target frame count from QPC elapsed time and duplicate the latest frame for gaps.
         LARGE_INTEGER now_qpc;
         QueryPerformanceCounter(&now_qpc);
         int64_t target = llround(
@@ -607,10 +563,7 @@ static DWORD WINAPI pacer_thread_proc(LPVOID)
 
 static void pacer_start()
 {
-    // media_start can reach pacer_start twice without a stop in between
-    // (video init failure + retry): a second CreateEventW/CreateThread would
-    // leak the first event handle and strand the first thread forever on an
-    // orphaned stop event.
+    // Stop an existing pacer before replacing its event and thread handles.
     if (g_pacer_running.load()) return;
     if (g_settings.video_fps <= 0) return;
     g_pacer_fps          = g_settings.video_fps;
@@ -649,10 +602,7 @@ static void pacer_stop()
     if (g_pacer_stop_event) {
         SetEvent(g_pacer_stop_event);
         if (g_pacer_thread) {
-            // Unbounded join: the loop always exits once the stop event is
-            // set (WAIT_FAILED included), so this cannot hang - and the old
-            // 3 s timeout closed the handles of a possibly-live thread,
-            // leaving a busy-spinning pacer using a closing encoder.
+            // Join before releasing handles or the encoder used by this worker.
             WaitForSingleObject(g_pacer_thread, INFINITE);
             CloseHandle(g_pacer_thread);
             g_pacer_thread = nullptr;
@@ -667,7 +617,6 @@ static void pacer_stop()
     pacer_release_buffers();
 }
 
-// ── Monitor enumeration / selection ──────────────────────────────────────────
 
 struct MonitorEntry {
     HMONITOR hmon = nullptr;
@@ -792,14 +741,8 @@ static void load_app_settings()
     log_path("settings", "config path: ", g_settings.user_config_path);
 }
 
-// Generates the first-frame thumbnail and inserts a row into the co-located
-// clip DB for a freshly written clip. Runs off the UI/tray thread (blocking
-// decode + DB I/O). `video_path` is the full path returned by the writer;
-// `source` is "replay" or "manual". Returns the new row id (> 0) or -1 on
-// failure; on success `on_cataloged` is invoked with the row id (the manual-
-// stop path uses it to flush pending bookmarks). Failures are logged, never
-// fatal - a clip with no DB row/thumb still plays and gets picked up by
-// reconcile later.
+// Blocking thumbnail/catalog work runs off the tray thread. Invoke on_cataloged
+// after insertion to flush pending manual-recording bookmarks.
 static int64_t catalog_clip(std::wstring video_path, std::string source,
                             double duration_seconds,
                             std::function<void(int64_t)> on_cataloged = {})
@@ -818,8 +761,6 @@ static int64_t catalog_clip(std::wstring video_path, std::string source,
     if (encoding::generate_thumbnail(video_path, thumb_path))
         thumb_stored = thumb_base;
     else
-        // Always surfaced (not gated by verbose logging): a missing thumbnail is
-        // the visible symptom, so the cause must be diagnosable by default.
         log_error_path("storage", "thumbnail generation failed for ", video_path);
 
     std::string error;
@@ -860,9 +801,7 @@ static int64_t catalog_clip(std::wstring video_path, std::string source,
     return row_id;
 }
 
-// Self-heal both catalogs on startup: drop rows whose video vanished, rebuild
-// missing thumbnails, and import pre-existing videos that have no row yet.
-// Detached background thread - never blocks startup.
+// Reconcile catalogs on a detached worker; startup does not wait for it.
 static void reconcile_catalogs()
 {
     const std::wstring clips_dir = g_settings.clips_directory;
@@ -889,11 +828,7 @@ static void reconcile_catalogs()
     }).detach();
 }
 
-// ── Pending bookmarks ─────────────────────────────────────────────────────────
-// Bookmarks are timestamped live (hotkey or IPC) while a manual recording runs
-// and flushed into recs.db when the recording stops and its clip row exists.
-// They are written by the engine (single writer) - the UI only reads/edits
-// them afterwards.
+// Timestamp live bookmarks during recording, then attach them after the clip row is inserted.
 struct PendingBookmark {
     double      time_seconds;
     std::string label;
@@ -959,11 +894,7 @@ static std::string add_bookmark_now()
     return {};
 }
 
-// Trims a clip's video file in place: writes a temp file (lossless remux-copy,
-// falling back to a re-encode when the container can't mux the codec), then
-// atomically replaces the original, updates the catalog duration, retimes
-// bookmarks into the new timeline (dropping ones outside the window) and
-// regenerates the thumbnail. Returns "" on success or an error message.
+// Trim into a sibling file, replace the media, then retime bookmarks and refresh the thumbnail.
 static std::string trim_clip(storage::ClipDb* db,
                              const std::wstring& folder,
                              int64_t id, double start, double end)
@@ -982,7 +913,7 @@ static std::string trim_clip(storage::ClipDb* db,
     if (start >= duration) return "start is past the end of the clip";
     const double eff_end = std::min(end, duration);
 
-    // Write to a sibling temp so a crash/power loss never destroys the clip.
+    // Keep the original media while producing the sibling trim file.
     std::wstring stem = p.stem().wstring();
     if (stem.empty()) stem = L"clip";
     const std::wstring tmp_path = folder + L"\\" + stem + L".trimming" + ext;
@@ -1023,22 +954,18 @@ static std::string trim_clip(storage::ClipDb* db,
         if (!updated) return "trim succeeded but bookmark update failed: " + err;
     }
 
-    // Thumbnail now shows the wrong frame; regenerate it (best effort) and
-    // bump the generation so the UI clip-watch reloads the row.
+    // Refresh the thumbnail and notify the UI after replacing the media.
     if (db->regenerate_thumbnail(id, &err)) {
         g_clip_generation.fetch_add(1, std::memory_order_relaxed);
     } else {
-        // Keep the old thumbnail: the clip still plays; reconcile/UI can
-        // regenerate on demand.
+        // Retain the previous thumbnail when regeneration fails.
         log_error("storage", ("clip_trim thumbnail regen failed: " + err).c_str());
         g_clip_generation.fetch_add(1, std::memory_order_relaxed);
     }
     return {};
 }
 
-// Performs a UI-driven clip mutation (favorite/hashtag/delete) on the IPC
-// thread. The recorder is the single writer, so the UI process routes these
-// here instead of writing the DB itself. Returns "" on success or an error message.
+// Catalog mutations run on IPC threads and return an empty string or an error.
 static std::string handle_clip_mutation(const ipc::ClipMutation& m)
 {
     std::wstring folder;
@@ -1069,12 +996,9 @@ static std::string handle_clip_mutation(const ipc::ClipMutation& m)
     else return "unknown mutation: " + m.method;
 
     if (!ok) {
-        // Always-on so a failed thumbnail regen / mutation is diagnosable.
         log_error("storage", ("clip mutation '" + m.method + "' failed: " + err).c_str());
     } else if (m.method == "clip_regen_thumb") {
-        // A regenerated thumbnail changes displayed data but doesn't insert a
-        // row; bump the generation so the UI clip-watch reloads and picks up the
-        // now-populated thumbnail_file.
+        // Notify the UI after changing a thumbnail without inserting a clip row.
         g_clip_generation.fetch_add(1, std::memory_order_relaxed);
     }
 
@@ -1087,12 +1011,7 @@ static void media_start(HWND hwnd);
 static void media_stop();
 static void tray_set_recording(bool recording);
 
-// ── Detection / multi-game / auto-record shared state (UI thread only) ─────────
-//
-// poll_active_game() computes these each detection pass; evaluate_capture_mode()
-// consumes them for the capture pipeline + auto-record state machine. Keeping the
-// two split means the inline poll_active_game() calls inside media_start() don't
-// trigger capture churn.
+// Detection, selection and auto-record state below belong to the tray thread.
 static uint64_t g_last_game_seen_ms  = 0;
 static bool     g_capture_mode_stopped = false; // capture idled off by game_only
 static bool     g_auto_recording_active = false;
@@ -1145,7 +1064,7 @@ static bool auto_record_start(HWND hwnd)
     return true;
 }
 
-// Stops + catalogs the current auto recording (never a user manual recording).
+// Stop only the automatically started recording.
 static void auto_record_stop()
 {
     if (!g_auto_recording_active ||
@@ -1177,8 +1096,7 @@ static void auto_record_stop()
 static void evaluate_capture_mode(HWND hwnd)
 {
     if (g_settings.capture_mode != "game_only") {
-        // Screen mode: full-screen capture always runs; detection still happened
-        // (naming/icon/candidates), but capture/auto-record here is a no-op.
+        // Screen mode bypasses game-only capture and auto-record transitions.
         g_capture_mode_stopped  = false;
         return;
     }
@@ -1190,7 +1108,6 @@ static void evaluate_capture_mode(HWND hwnd)
     const bool has_game = g_effective_game_pid != 0;
     const bool clip_without_game = g_settings.capture_clip_without_game;
 
-    // ── A game is available ──────────────────────────────────────────────────
     if (has_game) {
         g_last_game_seen_ms = now;
 
@@ -1202,9 +1119,7 @@ static void evaluate_capture_mode(HWND hwnd)
             g_capture_mode_stopped = false;
         }
 
-        // Auto-next-on-close: the recorded game closed while others remain - the
-        // effective target already moved on; stop the old recording and start the
-        // new target.
+        // When the recorded game exits, restart auto-recording for the new effective target.
         if (g_auto_state == AutoState::AutoRecording &&
             g_recording_game_pid != 0 &&
             g_recording_game_pid != g_effective_game_pid) {
@@ -1234,8 +1149,7 @@ static void evaluate_capture_mode(HWND hwnd)
         return;
     }
 
-    // ── No game detected ─────────────────────────────────────────────────────
-    // Stop an auto recording (never a user-started manual recording).
+    // Stop auto recording; leave user-started recording to its own controls.
     if (g_auto_recording_active) {
         auto_record_stop();
     } else if (g_recording.state() != recording::RecordingState::Idle) {
@@ -1392,7 +1306,6 @@ static void reload_settings_from_disk(HWND hwnd)
     }
 }
 
-// ── Audio routing ─────────────────────────────────────────────────────────────
 
 static settings::RuntimeAudioDevice runtime_audio_device(const audio::DeviceInfo& dev)
 {
@@ -1484,9 +1397,7 @@ static bool open_audio_track(int track)
     return ok;
 }
 
-// Number of enabled sources planned for each track (index 1..6). Used to decide
-// whether a track can be pushed directly (single source) or needs a mixer
-// (multiple sources on the same logical track). Recomputed before audio start.
+// Count routes per track before startup: one source feeds the encoder, multiple sources use a mixer.
 static std::array<int, 7> g_track_plan_count{};
 
 // Ensure a mixer exists for `track`, wired to feed that track's encoder.
@@ -1522,7 +1433,7 @@ static std::vector<AudioRoute> make_routes(const std::vector<int>& requested,
         if (g_track_plan_count[track] > 1) {
             encoding::TrackMixer* mixer = ensure_track_mixer(track);
             if (!mixer) continue;
-            // Mixed track: gain lives in the mixer source so summing is correct.
+            // Mixed-route gain is applied by the mixer.
             r.mixer_src = mixer->add_source(gain);
             if (r.mixer_src < 0) continue;
         }
@@ -1730,11 +1641,8 @@ static uint32_t resolve_configured_process_window(const settings::AudioSourceCon
     return match.process_id;
 }
 
-// Resolve a configured `process` audio source to a live PID. The PID is never
-// trusted as a persistent identity (it dies/recycles across reboots); we always
-// re-resolve from the live render sessions, matching by executable path first
-// and falling back to the process name. The saved process_id is used only as a
-// best-effort hint when it is still alive AND points at the wanted executable.
+// Resolve saved process sources from live sessions by path, then name. Treat
+// the saved PID only as a hint because Windows can recycle it.
 static uint32_t resolve_configured_process(const settings::AudioSourceConfig& source)
 {
     uint32_t window_pid = resolve_configured_process_window(source);
@@ -1814,8 +1722,7 @@ static void stop_audio_system()
 
 static void start_default_audio_system()
 {
-    // start_endpoint_source() already closes its own tracks on failure, so the
-    // return values are only informative here.
+    // Endpoint startup cleans its partial routes on failure.
     std::vector<int> desktop_tracks{1};
     start_endpoint_source(
         audio::WasapiCapture::Mode::Loopback,
@@ -1835,8 +1742,7 @@ static void start_default_audio_system()
 
 static void start_custom_audio_system()
 {
-    // Plan first: count how many enabled sources route to each track so make_routes()
-    // knows which tracks need a mixer (>= 2 sources) vs a direct encoder feed.
+    // Plan route counts before creating mixer sources.
     g_track_plan_count.fill(0);
     for (const auto& source : g_settings.audio_sources) {
         if (!source.enabled) continue;
@@ -1889,10 +1795,7 @@ static void start_custom_audio_system()
         } else if (source.type == "active_game") {
             g_active_game_tracks = tracks;
             g_active_game_gain = source.volume;
-            // Initial acquire: call poll_active_game() inline after audio start to pick
-            // up any game already running.  poll_active_game() uses the configured
-            // blacklist/whitelist and will set g_active_game_pid/capture/mode.
-            // If nothing is found yet the timer/hook will handle acquisition.
+            // Acquire the detected active-game audio source after audio startup.
         }
     }
 }
@@ -1925,8 +1828,7 @@ static audio::DetectConfig build_detect_config()
 {
     audio::DetectConfig cfg;
     cfg.min_confidence = g_settings.active_game.min_confidence;
-    // Keep the live game's foreground bonus stable while a Monolith window
-    // (e.g. Settings) holds focus, so detection isn't invalidated temporarily.
+    // Retain the tracked game foreground bonus while a Monolith window has focus.
     cfg.sticky_foreground_pid = g_active_game_pid;
     for (const auto& s : g_settings.active_game.blacklist_processes)
         cfg.blacklist.push_back(utf8_to_wide(s));
@@ -1957,17 +1859,8 @@ static void drop_active_game_capture(const char* reason_msg)
     log_msg("audio.game", reason_msg);
 }
 
-// Called from the UI thread (via WM_TIMER or WM_FAST_SCAN) to evaluate whether
-// the Active Game source should be acquired, retained, or switched to a new process.
-//
-// Hysteresis: a new candidate must remain the best choice for switch_debounce_ms
-// before the capture is swapped.  Only the Active Game capture is touched; other
-// captures, encoders, and the replay buffer are never restarted.
-// Drives ONLY the Active Game audio process-loopback capture toward `result`
-// (the effective target chosen by poll_active_game()). Does not publish the
-// active_game display block on the no-audio-source path - that is handled by
-// poll_active_game() so the UI shows the game even without an active-game audio
-// source configured.
+// Debounce target changes before swapping the active-game audio capture.
+// Detection publication and video/auto-record transitions belong to separate functions.
 static void poll_active_game_impl(const audio::ActiveGameResult& result)
 {
     if (g_active_game_tracks.empty()) return;
@@ -1979,7 +1872,6 @@ static void poll_active_game_impl(const audio::ActiveGameResult& result)
 
     uint32_t best_pid = result.process.process_id;
 
-    // ── No valid candidate ────────────────────────────────────────────────────
     if (best_pid == 0) {
         g_pending_game_pid      = 0;
         g_pending_game_first_ms = 0;
@@ -2001,7 +1893,6 @@ static void poll_active_game_impl(const audio::ActiveGameResult& result)
         return;
     }
 
-    // ── Same as current live capture: refresh status, no change ───────────────
     if (best_pid == g_active_game_pid) {
         g_pending_game_pid      = 0;
         g_pending_game_first_ms = 0;
@@ -2015,7 +1906,6 @@ static void poll_active_game_impl(const audio::ActiveGameResult& result)
         return;
     }
 
-    // ── No current capture and a valid candidate: acquire immediately ──────────
     if (g_active_game_pid == 0) {
         bool ok = start_process_source(best_pid, g_active_game_tracks,
                                        "audio.game", "active game audio started",
@@ -2050,7 +1940,6 @@ static void poll_active_game_impl(const audio::ActiveGameResult& result)
         return;
     }
 
-    // ── Different candidate: debounce before switching ────────────────────────
     DWORD now_ms = GetTickCount();
     if (g_pending_game_pid != best_pid) {
         // New pending candidate; reset the debounce timer.
@@ -2064,8 +1953,7 @@ static void poll_active_game_impl(const audio::ActiveGameResult& result)
     if (elapsed < static_cast<DWORD>(g_settings.active_game.switch_debounce_ms))
         return; // Not yet; keep waiting.
 
-    // Debounce passed → swap the Active Game capture.
-    // Start the new capture first (so there is minimal gap), then stop the old one.
+    // Acquire the new active-game source before releasing the prior capture.
     bool ok = start_process_source(best_pid, g_active_game_tracks,
                                    "audio.game", "active game switched",
                                    g_active_game_gain);
@@ -2079,7 +1967,6 @@ static void poll_active_game_impl(const audio::ActiveGameResult& result)
 
     audio::WasapiCapture* new_capture = g_audio_captures.back().capture.get();
 
-    // Remove old capture - only the Active Game source, nothing else.
     if (g_active_game_capture != nullptr) {
         for (auto it = g_audio_captures.begin(); it != g_audio_captures.end(); ++it) {
             if (it->capture.get() == g_active_game_capture) {
@@ -2152,11 +2039,8 @@ static const audio::GameCandidateInfo* resolve_effective_target(
     return best;
 }
 
-// Public entry point: run one DB-gated detection pass, resolve the effective
-// target, drive the Active Game audio capture toward it, publish the active game
-// + full candidate list, and flush runtime-status.json. Does NOT touch the
-// capture pipeline / auto-record - evaluate_capture_mode() does, from the shared
-// state this leaves behind.
+// Publish the detected target/candidates and drive active-game audio.
+// evaluate_capture_mode handles video and auto-record transitions.
 static void poll_active_game()
 {
     if (!g_settings.active_game.detection_enabled) {
@@ -2187,9 +2071,7 @@ static void poll_active_game()
 
     const audio::GameCandidateInfo* target = resolve_effective_target(candidates);
     g_effective_game_pid = target ? target->process.process_id : 0;
-    // Only the game_only window-capture path uses this (capture target + pacer
-    // frozen-frame). In screen mode we capture the whole monitor, so leave it
-    // null - a minimized game must NOT freeze full-screen capture.
+    // Only game-window capture freezes when its target is minimized.
     g_capture_target_hwnd.store(
         (target && g_settings.capture_mode == "game_only") ? target->capture_window : nullptr,
         std::memory_order_relaxed);
@@ -2251,9 +2133,7 @@ static void poll_active_game()
     publish_runtime_status();
 }
 
-// WinEvent hook callback - called on the UI thread when the foreground window changes.
-// Rate-limited fast scan: coalesces rapid events by checking g_fast_scan_pending,
-// then posts WM_FAST_SCAN so poll_active_game() runs on the next message-loop turn.
+// Coalesce foreground events and post WM_FAST_SCAN for the next message-loop turn.
 static void CALLBACK active_game_fg_hook(
     HWINEVENTHOOK /*hWinEventHook*/, DWORD /*event*/, HWND /*hwnd*/,
     LONG /*idObject*/, LONG /*idChild*/, DWORD /*dwEventThread*/, DWORD /*dwmsEventTime*/)
@@ -2282,7 +2162,6 @@ static void uninstall_fg_hook()
     g_fg_hook = nullptr;
 }
 
-// ── Media start / stop ────────────────────────────────────────────────────────
 
 struct WindowSearch {
     DWORD pid = 0;
@@ -2312,13 +2191,8 @@ static HWND main_window_for_process(uint32_t pid)
     return search.hwnd;
 }
 
-// Output resolution derives from a preset target height while preserving the
-// source aspect ratio. Never upscales beyond native (a preset taller than the
-// source falls back to source), so no pixels are invented. Shared by the
-// upfront GPU-downscale sizing (CaptureOptions::output_width/height, known
-// before the first frame for monitor capture) and the encoder-open fallback
-// (which resolves against the first captured frame's actual size, needed for
-// game_only window capture where native size isn't known upfront).
+// Use the preset height without upscaling; derive width from the source aspect ratio.
+// Window capture resolves its native size from the first frame.
 static void resolve_target_size(int src_w, int src_h, const std::string& preset,
                                  int* out_w, int* out_h)
 {
@@ -2346,7 +2220,6 @@ static void media_start(HWND hwnd)
     // stays down (replay disabled + recording idle).
     g_main_hwnd = hwnd;
 
-    // ── Replay buffer config ───────────────────────────────────────────────────
     apply_runtime_settings();
 
     // Do not run WGC/pacer/audio when no video output is active. Keep this
@@ -2358,14 +2231,11 @@ static void media_start(HWND hwnd)
         return;
     }
 
-    // ── Capture monitor from config (restart-required setting) ───────────────
     std::vector<MonitorEntry> monitors = enumerate_monitors();
     std::wstring used_device;
     HMONITOR hmon = monitor_from_settings(monitors, &used_device);
 
-    // Screen-mode auto-follow: with no manual monitor pin, capture the screen the
-    // detected game is on. A manual pick (monitor_device set) always wins and is
-    // already returned by monitor_from_settings above.
+    // A pinned monitor takes precedence over following the detected game.
     if (g_settings.capture_mode == "always" && g_settings.monitor_device.empty() &&
         g_effective_game_pid != 0) {
         HWND gw = main_window_for_process(g_effective_game_pid);
@@ -2408,25 +2278,20 @@ static void media_start(HWND hwnd)
     g_perf_bgra_memcpy_frames.store(0, std::memory_order_relaxed);
     g_perf_bgra_memcpy_time_us_total.store(0, std::memory_order_relaxed);
 
-    // ── Video encoder ─────────────────────────────────────────────────────────
     log_msg("encoding", "video encoder deferred until first WGC frame");
 
-    // ── Start pacer thread (OBS-style fixed-rate encoder feed) ────────────────
     pacer_start();
 
-    // ── Audio capture/routing ──────────────────────────────────────────────────
     start_audio_system();
     if (g_settings.active_game.detection_enabled) {
         // Detection runs in ALL modes now (game_only AND screen): it drives
         // naming/icon, the candidate list, and auto-record. Fixed 3 s cadence.
         SetTimer(hwnd, kActiveGameTimerId, kActiveGamePollMs, nullptr);
-        // Foreground-change fast scan is always on for snappy game switches.
         install_fg_hook();
         // Initial detection pass (doesn't wait for first timer tick).
         poll_active_game();
     }
 
-    // ── WGC display capture ───────────────────────────────────────────────────
     if (capture::is_supported()) {
         const settings::Config video_settings = g_settings;
         bool ok = g_video.start(hmon, [video_settings](capture::FrameInfo const& f) {
@@ -2549,15 +2414,12 @@ static void media_start(HWND hwnd)
             }
             // Push BGRA frame to pacer. Pacer thread drives encoder at fixed FPS.
             if (f.bgra_data == nullptr) return;
-            // Replay buffer disabled: encode only while a manual recording
-            // is running, so an idle tray app costs no encoder CPU.
+            // Skip encoding while both replay and manual recording are inactive.
             if (!g_replay_enabled.load(std::memory_order_relaxed) &&
                 g_recording.state() == recording::RecordingState::Idle)
                 return;
             if (!g_video_enc.is_open()) {
-                // Respect the post-failure backoff window so a transient open
-                // failure (e.g. GPU busy / driver reset) doesn't get re-probed on
-                // every single captured frame.
+                // Respect encoder-open backoff before retrying on a later captured frame.
                 if (GetTickCount64() <
                     g_video_enc_retry_after_ms.load(std::memory_order_acquire))
                     return;
@@ -2568,11 +2430,7 @@ static void media_start(HWND hwnd)
                     return;
                 }
 
-                // Resolves against the actually-captured frame size, which is
-                // already the GPU-downscaled size when CaptureOptions below
-                // configured one (this then just confirms it) - and is still
-                // native size in game_only mode (no upfront target there), so
-                // this remains the source of truth either way.
+                // Resolve against the delivered frame size, which may already be GPU-downscaled.
                 int g_enc_w_resolved = 0, g_enc_h_resolved = 0;
                 resolve_target_size(static_cast<int>(f.width), static_cast<int>(f.height),
                                      video_settings.resolution_preset,
@@ -2652,7 +2510,6 @@ static void media_start(HWND hwnd)
                         g_runtime_status.video_encoder_error = err;
                     }
                     publish_runtime_status();
-                    // Re-arm so a later frame can retry after the backoff window.
                     g_video_enc_retry_after_ms.store(
                         GetTickCount64() + kVideoEncRetryBackoffMs,
                         std::memory_order_release);
@@ -2666,16 +2523,12 @@ static void media_start(HWND hwnd)
                              static_cast<int>(f.height));
         }, [&]() {
             capture::CaptureOptions options;
-            // Capture border is always suppressed; the toggle was removed from the
-            // UI and the WGC yellow border is never wanted for a recorder.
+            // Request border suppression for recorder capture.
             options.show_border = false;
             options.max_readback_fps = std::max(1, g_settings.video_fps);
             options.allow_unlimited_readback = false;
 
-            // In game_only, capture the effective target's window (resolved by the
-            // detection poll). When there is no target (no game, or its window is
-            // unavailable) we fall back to full-screen monitor capture - which is
-            // also the clip-without-game path.
+            // Use the resolved game window in game_only mode; otherwise capture the monitor.
             HWND target = nullptr;
             if (g_settings.capture_mode == "game_only") {
                 target = g_capture_target_hwnd.load(std::memory_order_relaxed);
@@ -2693,8 +2546,7 @@ static void media_start(HWND hwnd)
             } else {
                 if (g_settings.capture_mode == "game_only")
                     log_msg("capture", "game_only: no game window, capturing full screen");
-                // Native monitor size is known upfront here (unlike a window
-                // target), so the GPU downscale target can be set before start().
+                // Set the GPU target before startup when native monitor size is known.
                 for (const auto& entry : monitors) {
                     if (entry.hmon == hmon) {
                         resolve_target_size(entry.info.width, entry.info.height,
@@ -2725,9 +2577,7 @@ static void media_start(HWND hwnd)
 
 static void media_stop()
 {
-    // Stop capture FIRST: while WGC delivers frames the pacer keeps swapping
-    // full-frame buffers, and a pacer stalled past its old join timeout could
-    // still touch the encoder we're about to close.
+    // Drain capture before stopping the pacer and closing its encoder.
     g_video.stop();
     pacer_stop();
     stop_audio_system();
@@ -2737,9 +2587,7 @@ static void media_stop()
         g_recording.stop(&path);
         if (!path.empty()) log_path("recording", "recording saved: ", path);
     }
-    // A recording killed here never reaches CMD_RECORDING_STOP, so stop the
-    // bookmark clock and drop any pending bookmarks (no clip row will exist
-    // to flush them into - otherwise they'd leak into the next recording).
+    // Stop the bookmark clock and discard pending entries when no clip will be cataloged.
     rec_clock_stop();
     clear_pending_bookmarks();
     g_video_enc_open_attempted.store(false, std::memory_order_release);
@@ -2751,7 +2599,6 @@ static void media_stop()
     log_msg("app", "capture + audio + encoding stopped");
 }
 
-// ── System tray ───────────────────────────────────────────────────────────────
 
 static NOTIFYICONDATAW g_nid;
 static HICON g_icon_base = nullptr;
@@ -2941,7 +2788,6 @@ static void tray_show_menu(HWND hwnd)
     DestroyMenu(menu);
 }
 
-// ── Hotkeys ───────────────────────────────────────────────────────────────────
 
 struct HotkeySpec {
     std::vector<UINT> keys;
@@ -3209,12 +3055,8 @@ static void hotkeys_unregister(HWND hwnd)
     memset(g_key_down, 0, sizeof(g_key_down));
 }
 
-// ── Command dispatch ──────────────────────────────────────────────────────────
 
-// True when a clip/record command must be blocked: game_only mode, no known game
-// running, and clip-without-game is off (so there is genuinely nothing to
-// capture). When clip-without-game is on we allow it - capture falls back to the
-// full screen.
+// Block game-only capture commands without a target unless screen fallback is enabled.
 static bool game_gate_blocks()
 {
     if (g_settings.capture_mode != "game_only") return false;
@@ -3285,9 +3127,7 @@ static void dispatch(Cmd cmd, HWND hwnd)
             if (path.empty()) log_msg("recording", "recording stopped: no complete output");
             else {
                 log_path("recording", "recording saved: ", path);
-                // Catalog off the UI thread - decode + DB I/O must not block it.
-                // The closure captures the recording folder so pending bookmarks
-                // flush into the right recs.db once the clip row exists.
+                // Catalog on a worker; capture the folder for the pending bookmark flush.
                 const std::wstring folder =
                     std::filesystem::path(path).parent_path().wstring();
                 std::thread(catalog_clip, path, std::string("manual"), 0.0,
@@ -3340,7 +3180,6 @@ static void dispatch(Cmd cmd, HWND hwnd)
     }
 }
 
-// ── Window procedure ──────────────────────────────────────────────────────────
 
 static LRESULT CALLBACK wnd_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
 {
@@ -3371,9 +3210,7 @@ static LRESULT CALLBACK wnd_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
         },
         add_bookmark_now,
         [] {
-            // update_close_ui for Updater.exe: close the UI process so ui\*
-            // can be swapped. Blocks until the process is gone; runs on an
-            // IPC client thread exactly like the WM_DESTROY shutdown path.
+            // Block this IPC worker until the UI process exits before replacing its files.
             settings_window::close_running();
         });
         publish_runtime_status();
@@ -3389,9 +3226,7 @@ static LRESULT CALLBACK wnd_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
         return DefWindowProcW(hwnd, msg, wp, lp);
 
     case WM_FAST_SCAN: {
-        // Foreground-change fast scan, rate-limited to one pass per second. Runs
-        // the capture/auto-record evaluation too, so the startup-focus grace and
-        // auto-record react immediately when the user foregrounds a game.
+        // Coalesce foreground scans at one-second intervals, including capture/auto-record evaluation.
         g_fast_scan_pending = false;
         constexpr DWORD kFastScanMinGapMs = 1000;
         DWORD now_ms = GetTickCount();
@@ -3438,10 +3273,7 @@ static LRESULT CALLBACK wnd_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
         return 0;
 
     case WM_REFRESH_AUDIO_SOURCES:
-        // On-demand re-enumeration requested by the Settings UI (e.g. when the
-        // user opens the "Add source" dropdown). Refresh the live audio session
-        // list and rewrite runtime-status.json synchronously so the caller sees
-        // current sessions as soon as this returns.
+        // Re-enumerate sessions/devices on an explicit Settings refresh request.
         refresh_audio_runtime_status();
         publish_runtime_status();
         return 0;
@@ -3451,7 +3283,6 @@ static LRESULT CALLBACK wnd_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
     }
 }
 
-// ── Entry point ───────────────────────────────────────────────────────────────
 
 int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE, PWSTR, int)
 {
@@ -3461,7 +3292,7 @@ int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE, PWSTR, int)
         return 0;
     }
 
-    // OBS-style: per-monitor DPI awareness so WGC returns physical pixels.
+    // Log initialization follows settings loading.
     SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);
 
     winrt::init_apartment(winrt::apartment_type::multi_threaded);
@@ -3473,9 +3304,7 @@ int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE, PWSTR, int)
     log_init(g_settings.logging_enabled);
     log_msg("app", "initializing (Monolith: replay + manual recording)");
     audio::set_log_sink([](const char* tag, const char* msg) { log_msg(tag, msg); });
-    // Game-list DB: detection is gated on it. Sync failures are surfaced via the
-    // always-on error log. init() kicks a background worker (startup + 72h sync);
-    // the tray/UI loop never blocks on the network or DB.
+    // Initialize the game-list refresh worker after logging is available.
     gamelist::set_log_sink([](const char* tag, const char* msg) { log_error(tag, msg); });
     gamelist::init(app_data_dir());
     reconcile_catalogs(); // self-heal clip catalogs on a background thread
diff --git a/app/recorder/src/settings_config.cpp b/app/recorder/src/settings_config.cpp
index 8c80d2e..eb47baf 100644
--- a/app/recorder/src/settings_config.cpp
+++ b/app/recorder/src/settings_config.cpp
@@ -179,8 +179,7 @@ std::string utf8_at(const json& doc, const char* section, const char* key, const
     return value_it->get<std::string>();
 }
 
-// Normalizes a hotkey chord string for case-insensitive comparison ("Ctrl+Shift+F8"
-// and "ctrl+shift+f8" collide). "NONE" (hotkey disabled) never collides with itself.
+// Compare enabled hotkeys case-insensitively; exclude NONE bindings.
 std::string normalize_hotkey(const std::string& chord)
 {
     std::string out = chord;
@@ -484,13 +483,8 @@ Config config_from_json(
     config.hotkey_pause_resume = utf8_at(doc, "hotkeys", "pause_resume", "Ctrl+Shift+F11");
     config.hotkey_add_bookmark = utf8_at(doc, "hotkeys", "add_bookmark", "Ctrl+Shift+F12");
 
-    // ── active_game detection settings ───────────────────────────────────────────
-    // Detection is a pure local heuristic over running processes (no network
-    // calls; Discord is only used elsewhere to enrich display artwork/name for
-    // a detected game) and polls on a fixed 5s cadence. Only detection_enabled
-    // and the internal process blacklist survive as configurable data; the
-    // timing tunables are hardcoded (ActiveGameSettings defaults) and no
-    // longer exposed in the UI.
+    // Detection timing uses ActiveGameSettings defaults; persisted input supplies
+    // the enable flag and blacklist.
     {
         auto ag_it = doc.find("active_game");
         const json* ag = (ag_it != doc.end() && ag_it->is_object()) ? &(*ag_it) : nullptr;
diff --git a/app/recorder/src/settings_config.h b/app/recorder/src/settings_config.h
index 7cc547d..4f93ce0 100644
--- a/app/recorder/src/settings_config.h
+++ b/app/recorder/src/settings_config.h
@@ -58,30 +58,20 @@ struct Config {
     // Active game detection settings.
     ActiveGameSettings active_game;
 
-    // Capture mode: "always" keeps the replay buffer running; "game_only" stops
-    // it after idle_timeout_seconds with no detected game and restarts on detect.
-    // Never stops an active manual recording.
+    // game_only pauses replay without a target; manual recording has separate controls.
     std::string capture_mode = "always"; // "always" | "game_only"
     int capture_idle_timeout_seconds = 300; // clamped 30-3600
     bool capture_auto_record = false;
-    // When true, the replay buffer stays active even with no detected game: in
-    // game_only mode it falls back to full-screen capture until a game appears.
-    // When false (default) the replay buffer is disabled once no game is present
-    // (after the idle timeout).
+    // Enable screen fallback for replay while no game is detected.
     bool capture_clip_without_game = false;
 
     // Capture (capture/encoder restart when no manual recording is active).
     std::wstring monitor_device;          // e.g. L"\\\\.\\DISPLAY1"; empty = primary
-    // Resolution is chosen as a preset height; the width is derived from the
-    // captured monitor's aspect ratio and never upscaled beyond the monitor.
-    // "source" keeps the native monitor resolution.
+    // Resolution presets specify height; preserve aspect ratio and native size as an upper bound.
     std::string resolution_preset = "source"; // source | 480p | 720p | 1080p | 1440p
     bool show_capture_border = false;
 
-    // Encoder (capture/encoder restart when no manual recording is active).
-    // Simplified surface: user picks CPU/GPU + codec; the engine resolves the
-    // concrete FFmpeg encoder from what the machine actually supports. Rate
-    // control is always CBR with the configured bitrate.
+    // Resolve device/codec preferences to an encoder; recording uses the target CBR bitrate.
     std::string encoder_device = "gpu";   // "gpu" | "cpu"
     std::string encoder_codec  = "h264";  // "h264" | "h265" | "av1"
     int video_bitrate_kbps = 20000;       // CBR target, clamped 1000-200000
@@ -117,9 +107,7 @@ LoadResult load(
 
 bool save(Config& config, std::string* error);
 
-// Snapshot of runtime capabilities written to AppData\Local\Monolith\
-// runtime-status.json so the Settings UI can offer only real choices
-// (available encoders, attached monitors, border-suppression support).
+// Runtime capabilities published to runtime-status.json for the Settings UI.
 struct RuntimeMonitor {
     std::wstring device;   // e.g. L"\\\\.\\DISPLAY1"
     int width = 0;
@@ -158,8 +146,6 @@ struct ActiveGameStatus {
     bool fast_scan_enabled = true;
 };
 
-// One detected game (DB-matched running process) offered to the UI so the user
-// can pick which to record/clip when several are running at once.
 struct GameCandidateStatus {
     uint32_t process_id = 0;
     std::wstring process_name;
@@ -186,8 +172,6 @@ struct RuntimeStatus {
     int encode_height = 0;
 };
 
-// Serializes RuntimeStatus to the JSON written to runtime-status.json.
-// Exposed so callers can diff against the previous content and skip no-op writes.
 std::string serialize_runtime_status(const RuntimeStatus& status);
 
 bool write_runtime_status(
diff --git a/app/recorder/src/settings_window.cpp b/app/recorder/src/settings_window.cpp
index 55df1bb..d470ca3 100644
--- a/app/recorder/src/settings_window.cpp
+++ b/app/recorder/src/settings_window.cpp
@@ -73,9 +73,7 @@ std::filesystem::path module_dir()
     return std::filesystem::path(path).parent_path();
 }
 
-// How to launch the UI: the executable, its command line, and the working
-// directory. The Tauri host is a single self-contained exe (Monolith.UI.exe)
-// that opens the WebView2 window, so a plain exe path is all that's needed.
+// Resolve the UI executable, command line and working directory.
 struct UiLaunch {
     std::filesystem::path exe;
     std::wstring          command_line; // quoted exe + args
diff --git a/app/recorder/src/updater.cpp b/app/recorder/src/updater.cpp
index e7f0315..5c9803e 100644
--- a/app/recorder/src/updater.cpp
+++ b/app/recorder/src/updater.cpp
@@ -116,8 +116,7 @@ void post_update_cleanup()
     const std::filesystem::path base = module_dir();
     if (base.empty()) return;
 
-    // *.old files parked by the updater's swap dance (a replaced engine exe
-    // or DLL cannot be deleted while loaded - deletion is retried here).
+    // Retry removal of parked .old files after the loaded binaries exit.
     const std::filesystem::path dirs[] = { base, base / "ui" };
     std::error_code ec;
     for (const auto& dir : dirs) {
diff --git a/app/recorder/src/updater.h b/app/recorder/src/updater.h
index f041f11..4d43bb5 100644
--- a/app/recorder/src/updater.h
+++ b/app/recorder/src/updater.h
@@ -1,12 +1,7 @@
 #pragma once
 
-// Component self-update for the recorder, delegated to Updater.exe
-// (app/updater). The dedicated process owns the whole flow: it fetches
-// update-manifest.json from the releases page, downloads only the
-// components whose version changed (engine / ui / updater are versioned
-// independently), verifies the Ed25519 signatures and swaps the files on
-// disk. The recorder merely launches it and cleans up the *.old files the
-// swap dance parks next to replaced binaries.
+// Updater.exe owns component download, verification and replacement.
+// The recorder launches it and cleans parked files on startup.
 namespace updater {
 
 // Store the automatic-check preference (settings: update.auto_check).
@@ -24,9 +19,7 @@ void check_now();
 // showing anything unless an update is actually available.
 void check_silent();
 
-// Deletes *.old leftovers from previous self-updates (app root + ui\) and
-// the legacy WinSparkle.dll of pre-component-updater installs. Call early
-// at startup; files still locked are retried on the next launch.
+// Clean parked files on startup; retry locked files on a later launch.
 void post_update_cleanup();
 
 // Kept for WM_DESTROY symmetry - nothing to shut down anymore.
diff --git a/app/updater/src-tauri/src/apply.rs b/app/updater/src-tauri/src/apply.rs
index 94fca4e..c43d5fb 100644
--- a/app/updater/src-tauri/src/apply.rs
+++ b/app/updater/src-tauri/src/apply.rs
@@ -12,8 +12,7 @@ fn wide(path: &Path) -> Vec<u16> {
 }
 
 fn to_old(path: &Path) -> Result<(), String> {
-    // Renaming a running image or a loaded DLL is legal on Windows; deleting
-    // is not. Park replaced files as *.old - swept on the next launch.
+    // Park replaced binaries as .old; retry deletion after their users exit.
     let old = old_path(path);
     unsafe {
         MoveFileExW(
@@ -44,8 +43,7 @@ fn place_file(staged: &Path, target: &Path) -> Result<(), String> {
         to_old(target)?;
     }
     if fs::rename(staged, target).is_err() {
-        // Same-volume rename should always work (staging lives inside the
-        // app dir); the copy+delete fallback covers exotic setups.
+        // Fall back to copy when the staging rename fails.
         if let Err(error) = fs::copy(staged, target) {
             if replaced {
                 unsafe {
@@ -71,10 +69,7 @@ fn place_file(staged: &Path, target: &Path) -> Result<(), String> {
     Ok(())
 }
 
-/// Moves every file of the extracted component tree into place under dest.
-/// Files already present in dest but not part of the tree are left alone -
-/// the app root also hosts Updater.exe and user-adjacent files that are not
-/// part of the engine zip.
+/// Replace files present in the staged component; leave unrelated destination files intact.
 pub fn place_tree(src: &Path, dest: &Path) -> Result<(), String> {
     place_tree_rec(src, src, dest)
 }
@@ -93,18 +88,13 @@ fn place_tree_rec(root: &Path, src: &Path, dest: &Path) -> Result<(), String> {
     Ok(())
 }
 
-/// Replaces Updater.exe itself: park the running image as .old, copy the new
-/// one in. The running process keeps executing from memory, so the swap is
-/// safe mid-flight; the parked image is swept on the next launch.
+/// Park the running updater image and place its replacement at the installed path.
 pub fn self_swap(new_exe: &Path) -> Result<(), String> {
     let current = std::env::current_exe().map_err(|e| format!("self path: {e}"))?;
     place_file(new_exe, &current)
 }
 
-/// Deletes *.old leftovers from previous applies (app root + ui\). A failure
-/// (file still held by a process that has not fully exited yet) is silently
-/// retried on the next launch. Also drops the legacy WinSparkle.dll from
-/// installs migrated off the old updater.
+/// Retry parked-file cleanup on later launches if files remain locked.
 pub fn sweep_old(app_dir: &Path) {
     let dirs = [app_dir.to_path_buf(), app_dir.join("ui")];
     for dir in dirs {
diff --git a/app/updater/src-tauri/src/download.rs b/app/updater/src-tauri/src/download.rs
index 6363161..65b98da 100644
--- a/app/updater/src-tauri/src/download.rs
+++ b/app/updater/src-tauri/src/download.rs
@@ -5,10 +5,7 @@ use std::io::Read;
 use std::path::Path;
 use std::sync::atomic::AtomicBool;
 
-// Public half of the Monolith Ed25519 signing key - the same pair WinSparkle
-// used. The private half lives in the CI secret WINSPARKLE_ED_PRIVATE_KEY and
-// signs each component zip (openssl pkeyutl -sign -rawin, Sparkle format);
-// scripts/generate-update-manifest.ps1 emits the signatures we verify here.
+// Release components are signed with the CI Ed25519 key; this is its public half.
 const PUBLIC_KEY_B64: &str = "GgyaSRupUFn5Omaa90w0H2xDTrqff2DdzRDtbeplvKA=";
 
 /// Sentinel error string signalling a user cancel (not a failure).
diff --git a/app/updater/src-tauri/src/engine_rpc.rs b/app/updater/src-tauri/src/engine_rpc.rs
index 9d4d133..f2b972e 100644
--- a/app/updater/src-tauri/src/engine_rpc.rs
+++ b/app/updater/src-tauri/src/engine_rpc.rs
@@ -100,9 +100,7 @@ pub fn close_ui() -> Result<(), String> {
 }
 
 pub fn request_engine_exit() {
-    // Fire and (mostly) forget: the engine tears its IPC server down during
-    // shutdown, so the reply - or even the connection - may never arrive.
-    // wait_engine_exit() is the real confirmation.
+    // Confirm shutdown through wait_engine_exit; the RPC reply can disappear during teardown.
     let _ = rpc("update_engine_exit");
 }
 
diff --git a/app/updater/src-tauri/src/http.rs b/app/updater/src-tauri/src/http.rs
index f82b5b7..1352c9f 100644
--- a/app/updater/src-tauri/src/http.rs
+++ b/app/updater/src-tauri/src/http.rs
@@ -1,11 +1,4 @@
-// Minimal WinHTTP client: manifest fetch + streaming download with progress.
-//
-// WinHTTP (not a Rust TLS stack) on purpose: the updater inherits the system
-// proxy configuration - the same behavior the WinSparkle era had - and stays
-// free of C dependencies, which also allows `cargo check --target
-// x86_64-pc-windows-msvc` from any host. Redirects (GitHub's
-// releases/latest/download → objects.githubusercontent.com) are followed by
-// WinHTTP's default policy.
+// Use WinHTTP for system proxy support and release redirects.
 
 use std::io::Write;
 use std::path::Path;
diff --git a/app/updater/src-tauri/src/main.rs b/app/updater/src-tauri/src/main.rs
index 57da512..1353836 100644
--- a/app/updater/src-tauri/src/main.rs
+++ b/app/updater/src-tauri/src/main.rs
@@ -1,17 +1,4 @@
-// Monolith Updater (Updater.exe) - component self-updater.
-//
-// Owns the whole update flow: fetch update-manifest.json from the releases
-// page, compare per-component versions (engine / ui / updater are versioned
-// independently - a UI-only release never touches the engine), download ONLY
-// the components whose version changed, verify sha256 + Ed25519 (same key
-// pair WinSparkle used), stage and swap files on disk (rename-to-.old dance),
-// and relaunch the engine. The recorder spawns this exe with --auto at
-// startup (silent unless an update exists) and from the tray "Check for
-// Updates…" (window immediately).
-//
-// The Preact frontend is a pure projection of "update-state" events plus a
-// few commands (start / cancel / retry). Layout on disk (installed):
-//   {app}\Monolith.exe  {app}\Updater.exe  {app}\ui\Monolith.UI.exe
+// Component updater host; publish state to the frontend over update-state events.
 
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
@@ -32,7 +19,6 @@ use std::time::Duration;
 use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindowBuilder};
 
 static CORE: OnceLock<Core> = OnceLock::new();
-// --force: reinstall even when versions match (testing / repair path).
 static FORCE: AtomicBool = AtomicBool::new(false);
 
 fn core() -> &'static Core {
@@ -56,7 +42,6 @@ fn fail(app: &AppHandle, message: &str) {
     emit_state(app);
 }
 
-// ── Commands (frontend) ─────────────────────────────────────────────────────
 
 #[tauri::command]
 fn updater_state() -> serde_json::Value {
@@ -90,10 +75,8 @@ fn updater_retry(app: AppHandle) {
     });
 }
 
-// ── Check ───────────────────────────────────────────────────────────────────
 
-/// Truncate to the first three numeric groups so semver can parse 4-part
-/// Windows FileVersions ("1.2.3.4" → "1.2.3").
+/// Use the first three Windows FileVersion fields for semver comparison.
 fn three_part(v: &str) -> String {
     v.split('.').take(3).collect::<Vec<_>>().join(".")
 }
@@ -106,7 +89,7 @@ fn run_check(app: &AppHandle, auto: bool) {
     let m = match manifest::fetch() {
         Ok(m) => m,
         Err(e) => {
-            // A failed background check must never nag the user.
+            // Silent startup checks suppress their error window.
             if auto {
                 std::process::exit(0);
             }
@@ -131,8 +114,7 @@ fn run_check(app: &AppHandle, auto: bool) {
             semver::Version::parse(&to),
         ) {
             (Ok(a), Ok(b)) => b > a,
-            // Unparseable version: fall back to inequality so the component
-            // still heals itself through a reinstall.
+            // Compare unparseable versions as strings to allow replacement.
             _ => from != to,
         };
         if force || newer {
@@ -186,9 +168,7 @@ fn run_check(app: &AppHandle, auto: bool) {
     spawn_recording_watch(app);
 }
 
-/// While the user decides (Available), mirror the engine's recording state
-/// so Update-now can be disabled during a recording (the engine restarts to
-/// apply engine updates - that would kill an active clip).
+/// Refresh recording state while awaiting user action; engine updates require recording to stop.
 fn spawn_recording_watch(app: &AppHandle) {
     let app = app.clone();
     std::thread::spawn(move || loop {
@@ -211,7 +191,6 @@ fn spawn_recording_watch(app: &AppHandle) {
     });
 }
 
-// ── Download + apply pipeline ───────────────────────────────────────────────
 
 fn set_comp(key: &str, mutate: impl FnOnce(&mut ComponentState)) {
     let mut s = core().state.lock().unwrap();
@@ -369,8 +348,7 @@ fn run_pipeline(app: &AppHandle) {
         }
     }
 
-    // Relaunch the engine before self-swapping so the new engine is already
-    // running even if this process dies right after the swap.
+    // Relaunch before replacing the running updater image.
     if has("engine") && engine_was_running {
         use std::process::{Command, Stdio};
         let _ = Command::new(app_dir.join("Monolith.exe"))
@@ -415,7 +393,6 @@ fn run_pipeline(app: &AppHandle) {
     set_phase(app, Phase::Done);
 }
 
-// ── Single instance ─────────────────────────────────────────────────────────
 
 fn focus_existing_instance() -> bool {
     use windows::core::HSTRING;
diff --git a/app/updater/src-tauri/src/paths.rs b/app/updater/src-tauri/src/paths.rs
index 088d8da..a62dd11 100644
--- a/app/updater/src-tauri/src/paths.rs
+++ b/app/updater/src-tauri/src/paths.rs
@@ -7,14 +7,8 @@ pub fn exe_dir() -> PathBuf {
         .unwrap_or_else(|| PathBuf::from("."))
 }
 
-/// Directory where the installed app lives (Monolith.exe, Updater.exe, ui\).
-/// Resolution order:
-/// 1. `MONOLITH_APP_DIR` env override (tests / portable layouts);
-/// 2. the exe's own dir when it contains Monolith.exe (installed layout, or
-///    the CMake output dir where the build copies both exes);
-/// 3. dev fallback: walking up from a cargo target dir finds the repo root
-///    (recognized by app/desktop-ui + app/updater) and uses the CMake
-///    release output dir.
+/// Resolve the app directory from MONOLITH_APP_DIR, the installed layout,
+/// then the development CMake output.
 pub fn app_dir() -> PathBuf {
     if let Ok(dir) = std::env::var("MONOLITH_APP_DIR") {
         if !dir.is_empty() {
diff --git a/app/updater/src-tauri/src/versions.rs b/app/updater/src-tauri/src/versions.rs
index 0594c23..4440564 100644
--- a/app/updater/src-tauri/src/versions.rs
+++ b/app/updater/src-tauri/src/versions.rs
@@ -24,10 +24,7 @@ pub fn installed() -> Installed {
     }
 }
 
-/// Persists the last-applied per-component versions. The exe FileVersion is
-/// the primary source; this file catches exes whose resource block is
-/// missing or unreadable (and lets the updater's own version survive
-/// self-swaps even if the new exe ever ships without a resource).
+/// components.json is a fallback when installed executable version resources are unavailable.
 pub fn write_components_json(v: &Installed) {
     let path = paths::app_dir().join("components.json");
     if let Ok(json) = serde_json::to_string_pretty(v) {
@@ -40,10 +37,7 @@ fn read_components_json() -> Option<Installed> {
     serde_json::from_str(&text).ok()
 }
 
-/// Reads the Win32 VERSIONINFO FileVersion ("major.minor.patch[.build]") via
-/// the fixed, translation-independent block - no StringFileInfo lookup
-/// needed. Returns None when the file is missing or carries no version
-/// resource.
+/// Read the translation-independent fixed VERSIONINFO block.
 fn file_version(path: &Path) -> Option<String> {
     if !path.is_file() {
         return None;
diff --git a/app/updater/ui/src/updater.tsx b/app/updater/ui/src/updater.tsx
index 59e6278..6e97689 100644
--- a/app/updater/ui/src/updater.tsx
+++ b/app/updater/ui/src/updater.tsx
@@ -1,7 +1,4 @@
-// Updater window view. All state lives in the Rust host (src-tauri/src):
-// the frontend is a pure projection of the "update-state" events plus a few
-// commands (start / cancel / retry). Phases: checking → upToDate | available
-// → downloading → applying → done | failed.
+// Rust owns updater state; the frontend renders events and invokes actions.
 
 import { useEffect, useState } from "preact/hooks";
 import { invoke } from "@tauri-apps/api/core";
@@ -84,7 +81,6 @@ function prettyTag(tag: string): string {
   return tag.replace(/^v/, "");
 }
 
-// ── Icons (inline SVG, same approach as the main app's shell/icons.tsx) ─────
 
 function IconEngine() {
   return (
@@ -129,7 +125,6 @@ function IconCheck() {
   );
 }
 
-// ── Pieces ────────────────────────────────────────────────────────────────────
 
 function Titlebar({ closable }: { closable: boolean }) {
   const win = getCurrentWindow();
@@ -317,7 +312,6 @@ function ErrorState({ message, onRetry }: { message: string; onRetry: () => void
   );
 }
 
-// ── Buffer bar (signature): the window fills like the replay buffer ──────────
 
 function BufferBar({ state }: { state: UpdateState }) {
   const total = state.components.reduce((acc, c) => acc + c.size, 0);
@@ -354,7 +348,6 @@ function BufferBar({ state }: { state: UpdateState }) {
   );
 }
 
-// ── Root ─────────────────────────────────────────────────────────────────────
 
 export function Updater() {
   const [state, setState] = useState<UpdateState | null>(null);
@@ -461,8 +454,6 @@ export function Updater() {
     );
   }
 
-  // Footer varies per phase; the available/downloading phases keep the
-  // primary actions here so the body stays a pure projection of state.
   let foot;
   if (phase === "checking" || phase === "applying" || phase === "failed") {
     foot = null; // ErrorState renders its own actions inline.
diff --git a/app/updater/ui/styles.css b/app/updater/ui/styles.css
index 0691571..9847dfd 100644
--- a/app/updater/ui/styles.css
+++ b/app/updater/ui/styles.css
@@ -50,8 +50,6 @@ body {
 
 #app { height: 100%; display: flex; flex-direction: column; }
 
-/* ── Mini titlebar ─────────────────────────────────────────────────────── */
-
 .tb {
   height: 40px;
   flex: none;
@@ -98,8 +96,6 @@ body {
 .tb-close:hover { background: var(--danger); color: #fff; }
 .tb-close:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
 
-/* ── Body ──────────────────────────────────────────────────────────────── */
-
 .upd-body {
   flex: 1;
   min-height: 0;
@@ -117,8 +113,6 @@ body {
   border: 2px solid var(--bg);
 }
 
-/* Headline zone: release version + meta */
-
 .release { display: flex; flex-direction: column; gap: 6px; }
 
 .release-tag {
@@ -151,8 +145,6 @@ body {
 .release-meta a:hover { color: var(--accent-hi); border-bottom-color: var(--accent-line); }
 .release-meta a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 2px; }
 
-/* ── Component cards ───────────────────────────────────────────────────── */
-
 .comps { display: flex; flex-direction: column; gap: 8px; }
 
 .comps-label {
@@ -223,8 +215,6 @@ body {
   border-left: 1px solid var(--line);
 }
 
-/* Per-component meter (downloading / verifying) */
-
 .meter {
   height: 3px;
   border-radius: 2px;
@@ -255,8 +245,6 @@ body {
 .comp-row .stat.ok { color: var(--ok); }
 .comp-row .stat.err { color: var(--danger); }
 
-/* Total line above the footer */
-
 .total {
   display: flex;
   align-items: center;
@@ -269,8 +257,6 @@ body {
 
 .total strong { color: var(--dim); font-weight: 600; }
 
-/* Recording notice (update deferred) */
-
 .notice {
   display: flex;
   gap: 10px;
@@ -283,8 +269,6 @@ body {
   color: #f2b7b2;
 }
 
-/* ── Centered states: checking / up to date / applying / done ─────────── */
-
 .center {
   flex: 1;
   display: flex;
@@ -324,8 +308,6 @@ body {
 
 .center-vers b { color: var(--dim); font-weight: 600; }
 
-/* Loading dots (same rhythm as the main app) */
-
 .dots { display: flex; gap: 5px; }
 
 .dots i {
@@ -344,8 +326,6 @@ body {
   30% { opacity: 1; transform: translateY(-3px); }
 }
 
-/* Applying: indeterminate sweep, like a buffer flush */
-
 .sweep {
   width: 200px;
   height: 3px;
@@ -370,8 +350,6 @@ body {
   100% { transform: translateX(260%); }
 }
 
-/* Error block */
-
 .error-box {
   background: var(--danger-soft);
   border: 1px solid rgba(229, 84, 75, 0.28);
@@ -386,8 +364,6 @@ body {
 
 .error-box .title { font-weight: 700; color: var(--danger); }
 
-/* ── Footer actions ────────────────────────────────────────────────────── */
-
 .foot {
   flex: none;
   display: flex;
@@ -428,8 +404,6 @@ body {
 
 .btn:disabled { opacity: 0.38; }
 
-/* ── Buffer bar (signature) ────────────────────────────────────────────── */
-
 .buffer {
   flex: none;
   height: 18px;
@@ -462,8 +436,6 @@ body {
 
 .buffer.live .buffer-fill { background: var(--accent); box-shadow: 0 0 8px rgba(157, 180, 209, 0.5); }
 
-/* ── Reduced motion ────────────────────────────────────────────────────── */
-
 @media (prefers-reduced-motion: reduce) {
   .dots i, .sweep::after { animation-duration: 2.4s; }
   .meter > i, .buffer-fill { transition: none; }
diff --git a/app/updater/vite.config.ts b/app/updater/vite.config.ts
index 570bfdc..80025f9 100644
--- a/app/updater/vite.config.ts
+++ b/app/updater/vite.config.ts
@@ -9,7 +9,7 @@ export default defineConfig({
     emptyOutDir: true,
     target: "chrome110", // WebView2 is evergreen Edge/Chromium
   },
-  // Fixed port + strictPort so it matches src-tauri/tauri.conf.json's devUrl.
+  // Keep the dev port aligned with tauri.conf.json.
   server: {
     port: 1421,
     strictPort: true,
diff --git a/docs/audit/2026-10-08.md b/docs/audit/2026-10-08.md
index cbfe3a6..93900a4 100644
--- a/docs/audit/2026-10-08.md
+++ b/docs/audit/2026-10-08.md
@@ -44,7 +44,7 @@ New CI runs the native, Rust, Stream Deck and frontend checks on pull requests,
 
 The separate comment-only branch removes decorative separators, obsolete migration/task narratives, descriptions already apparent from names, and unsubstantiated claims of safety or correctness. Retained comments state nonobvious units, clock/ordering rules, callback/resource ownership, caller constraints and format limitations in brief English. License notices and tool directives remain. Generated plugin JavaScript is kept aligned with its TypeScript source.
 
-Validation compares the surviving source lines against the audit parent, ignoring only full-line comments and blank lines, and reruns TypeScript/plugin builds. This is a source-preservation check, not a general-purpose language parser.
+Validation compares the surviving source lines against the audit parent, ignoring full-line comments, blank lines and three explicitly checked inline field annotations, and reruns TypeScript/plugin builds. This is a source-preservation check, not a general-purpose language parser.
 
 ## PR 3: startup DLL failure and other release fixes
 
@@ -69,7 +69,8 @@ This corrects the packaging contract for the reported startup failure. It does n
 | Stream Deck | TypeScript build and one loopback integration regression pass. |
 | Packaging | 8 PowerShell verifier regression cases pass. |
 | Repository | `git diff --check` and `scripts/check-text.py` pass. |
-| Windows Actions | Build started on the packaging PR. Final CI status must be read from the PR checks; initial iterations exposed and corrected the x264 archive and vcpkg overlay failures. |
+| GitHub core Actions | All stages passed in [run 37712299113](https://github.com/fraa2a/Monolith/actions/runs/37712299113): native, Rust, Windows-target module check, plugin and both frontend builds. |
+| Windows Actions | Full build is still compiling dependencies. Final status must be read from the PR checks; initial iterations exposed and corrected the x264 archive and vcpkg overlay failures. |
 
 Native tests use small synthetic media and Linux compatibility shims. They do not exercise actual WGC, WASAPI, D3D11, hardware encoders, Windows file sharing or installer execution. Fixture-pressure AAC reset warnings are distinct from the checked continuous timeline. Performance changes bound memory/work and remove repeated I/O; FPS, CPU/GPU load and user-visible latency have not been benchmarked.
 
@@ -93,3 +94,9 @@ Native tests use small synthetic media and Linux compatibility shims. They do no
 | O14 | Release gate | Clean Windows 11 install/start, WebView2 prerequisites, loaded-DLL replacement and capture stop/restart stress remain untested. Test the actual installer payload on a machine without developer runtimes and preserve logs. |
 
 The three PRs are intended for review. No merge, release tag, installer publication or production deployment is included.
+
+## Comment cleanup validation checkpoint
+
+326 comment groups were changed across 65 source files, plus brief inline contract corrections, two CSS files and the generated plugin counterparts. All surviving source lines in the 69 code/style/generated files match the audit parent after excluding only comment/blank lines and three named inline field annotations. Checked-in plugin JavaScript matches compiler output. Both frontend production builds produced the same asset hashes as the audit build. This check is deliberately scoped to these edits, not advertised as a general parser.
+
+Published technical PR: [#4](https://github.com/fraa2a/Monolith/pull/4). Packaging and release fixes: [#3](https://github.com/fraa2a/Monolith/pull/3). Review the comment PR against `fix/code-audit` so functional fixes stay outside its diff.
diff --git a/docs/handover/ACTIVE_HANDOVER.md b/docs/handover/ACTIVE_HANDOVER.md
index 676ee2f..c5723a1 100644
--- a/docs/handover/ACTIVE_HANDOVER.md
+++ b/docs/handover/ACTIVE_HANDOVER.md
@@ -461,3 +461,5 @@ The user authorized autonomous publication of all three English PRs after checks
 Technical audit changes and local regression evidence are in `docs/audit/2026-10-08.md`; `file-inventory.md` inventories every tracked/new file. PCM/mixer/recording/media, Rust catalogs/RPC/integrity, storage, frontends, plugin and packaging verifier checks passed. Windows native/Tauri runtime and clean installer launch are not certified. O01-O14 explicitly preserve unresolved architectural/runtime findings. Historical report findings must not all be marked closed.
 
 Comment cleanup follows on a separate branch based on the technical PR. Review stack: packaging, technical audit, comment cleanup.
+
+Comment cleanup checkpoint: audit PR #4 is published and its complete core Actions workflow passed. Comment-only source preservation passed across 69 code/style/generated files; generated plugin JS matches the compiler, and both frontend asset hashes match the audit build. Windows full build remains in dependency compilation. The report contains the validation scope and unresolved work.
diff --git a/libs/audio/audio.cpp b/libs/audio/audio.cpp
index 7a1a020..ad779a8 100644
--- a/libs/audio/audio.cpp
+++ b/libs/audio/audio.cpp
@@ -218,10 +218,7 @@ static void capture_thread(ImplT* impl)
     const uint16_t bit_depth = impl->mix_fmt->wBitsPerSample;
 
     while (impl->running.load(std::memory_order_acquire)) {
-        // Event-driven: block until WASAPI signals a buffer is ready (no busy
-        // polling).  A 200 ms timeout bounds shutdown latency and guards against
-        // a missed signal.  Loopback streams only raise the event while audio is
-        // flowing, so the timeout also lets us re-check `running` during silence.
+        // Wait for WASAPI buffer events rather than polling; the running flag controls shutdown.
         if (impl->event)
             WaitForSingleObject(impl->event, 200);
 
@@ -379,9 +376,7 @@ std::vector<ProcessAudioSessionInfo> enumerate_render_sessions()
         __uuidof(IMMDeviceEnumerator), enumerator.put_void());
     if (FAILED(hr)) return result;
 
-    // Enumerate sessions on every active render endpoint, not just the default
-    // one: an app (e.g. Discord) may render to a non-default output device, and
-    // its session would otherwise never appear in the source list.
+    // Enumerate sessions on all render endpoints, including non-default devices.
     winrt::com_ptr<IMMDeviceCollection> devices;
     if (FAILED(enumerator->EnumAudioEndpoints(eRender, DEVICE_STATE_ACTIVE, devices.put())))
         return result;
@@ -427,9 +422,7 @@ static std::wstring to_lower(std::wstring s)
     return s;
 }
 
-// Monolith's own processes (recorder + Settings sidecar).  Used so that opening
-// the Settings window does not steal the foreground bonus from the live game,
-// and shared with the shell/system exclusion list below.
+// Keep the tracked game focus bonus when Monolith owns the foreground window.
 static bool is_self_process(const std::wstring& lower_name)
 {
     return lower_name == L"monolith.exe" || lower_name == L"monolith.settings.exe";
@@ -524,10 +517,7 @@ static BOOL CALLBACK annotate_window_enum_proc(HWND hwnd, LPARAM lp)
     return TRUE;
 }
 
-// True when `title` plausibly names the DB game `display_name`: the title
-// contains the whole display name, or any of its alphanumeric tokens of length
-// >= 3. Case-insensitive. Only used to disambiguate several processes sharing
-// one executable; a loose match here just biases selection, never gates it.
+// Match window titles against database names to disambiguate shared executables.
 static bool title_matches_db_name(const std::string& display_name_utf8,
                                   const std::wstring& window_title)
 {
@@ -567,17 +557,14 @@ std::vector<GameCandidateInfo> detect_game_candidates(const DetectConfig& cfg)
     DWORD fg_pid = 0;
     if (fg) GetWindowThreadProcessId(fg, &fg_pid);
 
-    // Sticky foreground: when our own recorder/Settings window holds focus,
-    // substitute the caller-supplied live game pid so it keeps being marked
-    // foreground while a Monolith window is up.
+    // Use the tracked game PID as a foreground hint while Monolith has focus.
     if (fg_pid != 0 && cfg.sticky_foreground_pid != 0) {
         ProcessInfo fg_info = process_info(fg_pid);
         if (is_self_process(to_lower(fg_info.process_name)))
             fg_pid = cfg.sticky_foreground_pid;
     }
 
-    // Enumerate ALL processes (not just windows) so alt-tabbed / loading games
-    // still match. Gate each on game-list membership.
+    // Check all running processes against game-list membership, including windowless games.
     HANDLE snap = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
     if (snap == INVALID_HANDLE_VALUE) return out;
 
@@ -612,9 +599,7 @@ std::vector<GameCandidateInfo> detect_game_candidates(const DetectConfig& cfg)
             ci.process = process_info(pid);
             if (ci.process.process_name.empty())
                 ci.process.process_name = pe.szExeFile;
-            // Provisional identity: the first game registered for this exe. When
-            // the exe is shared it is refined by window title after the window
-            // pass below. Always a DB display name (Bug 2: never a prettified exe).
+            // Refine shared-executable identity with the main-window title below.
             ci.display_name   = it->second.front().display_name;
             ci.discord_app_id = it->second.front().discord_app_id;
             ci.has_session    = has_audio_session(pid);
@@ -643,10 +628,7 @@ std::vector<GameCandidateInfo> detect_game_candidates(const DetectConfig& cfg)
                 ci.process.window_title = fit->second.title;
         }
 
-        // Disambiguate shared executables (e.g. javaw.exe used by Minecraft,
-        // Spiral Knights, ...): pick the game whose name matches the window
-        // title. With a single registered game there is nothing to resolve; if
-        // none matches, the provisional first game stands (normal behavior).
+        // Use the main-window title to select among games sharing an executable.
         const gamelist::GameList& entries = *cand_entries[i];
         if (entries.size() > 1 && !ci.process.window_title.empty()) {
             for (const auto& e : entries) {
@@ -829,9 +811,7 @@ bool WasapiCapture::start_process_loopback(uint32_t process_id, PacketCallback c
         return false;
     }
 
-    // OBS-style process loopback: the virtual device has no reliable
-    // GetMixFormat path, so we provide the capture format up front, then use
-    // WASAPI event callbacks to wake only when process audio is available.
+    // Provide process-loopback format explicitly; the virtual device lacks a reliable GetMixFormat.
     auto* wf = static_cast<WAVEFORMATEXTENSIBLE*>(
         CoTaskMemAlloc(sizeof(WAVEFORMATEXTENSIBLE)));
     if (!wf) { stop(); return false; }
@@ -849,7 +829,6 @@ bool WasapiCapture::start_process_loopback(uint32_t process_id, PacketCallback c
     wf->SubFormat              = kSubTypeFloat; // KSDATAFORMAT_SUBTYPE_IEEE_FLOAT
     impl_->mix_fmt = reinterpret_cast<WAVEFORMATEX*>(wf);
 
-    // Use WASAPI event callbacks like OBS, not timer polling.
     DWORD flags = AUDCLNT_STREAMFLAGS_LOOPBACK | AUDCLNT_STREAMFLAGS_EVENTCALLBACK;
     hr = impl_->client->Initialize(
         AUDCLNT_SHAREMODE_SHARED,
diff --git a/libs/audio/audio.h b/libs/audio/audio.h
index d289a48..cd9b40a 100644
--- a/libs/audio/audio.h
+++ b/libs/audio/audio.h
@@ -31,9 +31,7 @@ struct PacketInfo {
 
 using PacketCallback = std::function<void(const PacketInfo&)>;
 
-// Optional diagnostic log sink (tag, message). The host wires this to its own
-// logger so audio-library diagnostics (e.g. process-loopback HRESULT failures)
-// land in the app log. Pass nullptr to disable. Set once at startup.
+// Set the diagnostic sink once before starting capture.
 void set_log_sink(std::function<void(const char* tag, const char* msg)> sink);
 
 struct DeviceInfo {
@@ -59,17 +57,13 @@ std::vector<ProcessAudioSessionInfo> enumerate_render_sessions();
 ProcessInfo active_foreground_process();
 
 // Config passed to detect_active_game() to drive blacklist/whitelist/confidence.
-// All exe names in blacklist/whitelist/manual_games are compared case-insensitively.
+// Blacklist names are matched case-insensitively; legacy whitelist fields are inert.
 struct DetectConfig {
     std::vector<std::wstring> blacklist;    // processes to reject unconditionally
-    std::vector<std::wstring> whitelist;    // processes that receive a strong bonus
-    std::vector<std::wstring> manual_games; // user-explicitly-chosen games (strong bonus)
-    int min_confidence = 50;               // 0-100; candidates below this are discarded
-    // When Monolith's own window (recorder or Settings) is in the foreground,
-    // the real game loses its foreground bonus and may drop below
-    // min_confidence - invalidating detection while Settings is open.  Set this
-    // to the currently-tracked game pid so its foreground bonus stays "sticky"
-    // while a Monolith window holds focus.  0 = no sticky fallback.
+    std::vector<std::wstring> whitelist;    // legacy input, ignored by database detection
+    std::vector<std::wstring> manual_games; // legacy input, ignored by database detection
+    int min_confidence = 50;               // legacy input, ignored by database detection
+    // Retain the tracked game foreground bonus while Monolith has focus; 0 disables it.
     uint32_t sticky_foreground_pid = 0;
 };
 
@@ -84,11 +78,8 @@ struct ActiveGameResult {
     bool fullscreen  = false;
 };
 
-// One running process whose executable is present in the local game-list DB.
-// Detection is DB-gated: only DB-matched processes ever become candidates. The
-// window facts (foreground/fullscreen/capture_window) only order candidates and
-// select the capture target - they never gate membership. display_name /
-// discord_app_id come from the DB (UTF-8).
+// Candidates require local database membership. Window facts rank them;
+// display names and app IDs come from the database as UTF-8.
 struct GameCandidateInfo {
     ProcessInfo process;
     std::string display_name;
@@ -97,24 +88,15 @@ struct GameCandidateInfo {
     bool     fullscreen = false;
     bool     has_session = false;    // has an active audio render session
     HWND     capture_window = nullptr; // main window to capture, if any
-    // True when several games share this executable (e.g. many Java games use
-    // javaw.exe) AND the main-window title matched one of them, so display_name/
-    // discord_app_id below were resolved to that specific game rather than an
-    // arbitrary same-exe sibling. Purely informational.
+    // Marks shared-executable identity resolved through a window-title match.
     bool     title_matches_db = false;
 };
 
-// DB-gated detection: returns every running process whose exe basename is in the
-// game-list DB (minus the user blacklist and built-in shell/self processes).
-// Selection among candidates is the caller's job. Empty when nothing matches or
-// the DB hasn't synced yet.
+// Return database-matched processes minus blacklist/self/shell entries; callers select the target.
 std::vector<GameCandidateInfo> detect_game_candidates(const DetectConfig& cfg);
 
-// Config-driven active-game detection, now DB-gated: returns the single best
-// candidate from detect_game_candidates (foreground > fullscreen > audio session
-// > window area). process_id == 0 when nothing qualifies. The blacklist and
-// sticky_foreground_pid in cfg are honored; whitelist/manual_games/min_confidence
-// are inert (detection is purely DB membership now).
+// Rank database candidates by foreground, fullscreen, audio and area.
+// A zero process_id means no target; legacy confidence/whitelist fields are inert.
 ActiveGameResult detect_active_game(const DetectConfig& cfg);
 
 // Convenience overload: built-in defaults (shell/Monolith excluded). Returns the
@@ -140,7 +122,7 @@ class WasapiCapture {
     WasapiCapture& operator=(const WasapiCapture&) = delete;
 
     // COM must be initialized on the calling thread before start().
-    // cb is invoked from the internal capture thread - must be thread-safe.
+    // cb runs on the capture thread; synchronize its shared state.
     bool start(Mode mode, PacketCallback cb);
     bool start_device(Mode mode, const std::wstring& device_id, PacketCallback cb);
     bool start_process_loopback(uint32_t process_id, PacketCallback cb);
diff --git a/libs/capture/capture.cpp b/libs/capture/capture.cpp
index 313c307..d99e682 100644
--- a/libs/capture/capture.cpp
+++ b/libs/capture/capture.cpp
@@ -26,7 +26,6 @@ namespace wgdx = winrt::Windows::Graphics::DirectX;
 
 namespace capture {
 
-// ── Impl ──────────────────────────────────────────────────────────────────────
 
 class FrameGate {
 public:
@@ -66,10 +65,7 @@ struct DisplayCapture::Impl {
     uint32_t                              staging_w = 0;
     uint32_t                              staging_h = 0;
 
-    // GPU pre-readback downscale (see CaptureOptions::output_width/height).
-    // Absent/null when the device doesn't expose D3D11 video support, or
-    // while no downscale is configured - the CopyResource(native) path is
-    // then used unconditionally, identical to pre-downscale behavior.
+    // Keep GPU downscale resources separate from the native capture texture.
     winrt::com_ptr<ID3D11VideoDevice>              video_device;
     winrt::com_ptr<ID3D11VideoContext>             video_ctx;
     winrt::com_ptr<ID3D11VideoProcessorEnumerator> vp_enum;
@@ -102,7 +98,6 @@ struct DisplayCapture::Impl {
     bool                  handler_registered = false;
 };
 
-// ── Helpers ───────────────────────────────────────────────────────────────────
 
 bool is_supported()
 {
@@ -158,10 +153,7 @@ static wgc::GraphicsCaptureItem item_from_window(HWND hwnd)
     return item;
 }
 
-// (Re)creates the video processor and its scaled output texture for the
-// given source -> destination size. No-op if already configured for the
-// same sizes. Returns false (leaving impl in a "not scaled" state) on any
-// failure, so callers fall back to native-resolution CopyResource.
+// Recreate the GPU video processor when source or output size changes.
 static bool ensure_video_processor(DisplayCapture::Impl* impl,
                                     uint32_t src_w, uint32_t src_h,
                                     uint32_t dst_w, uint32_t dst_h)
@@ -250,7 +242,6 @@ static bool gpu_downscale(DisplayCapture::Impl* impl, ID3D11Texture2D* src_tex,
         impl->video_processor.get(), out_view.get(), 0, 1, &stream));
 }
 
-// ── DisplayCapture ────────────────────────────────────────────────────────────
 
 DisplayCapture::DisplayCapture() : impl_(std::make_shared<Impl>()) {}
 DisplayCapture::~DisplayCapture() { stop(); }
@@ -374,12 +365,7 @@ bool DisplayCapture::start(HMONITOR hmon, FrameCallback cb, CaptureOptions optio
                 winrt::com_ptr<ID3D11Texture2D> gpu_tex;
                 if (access && SUCCEEDED(access->GetInterface(IID_PPV_ARGS(gpu_tex.put())))) {
 
-                    // GPU pre-readback downscale: when a smaller output size is
-                    // configured, scale on the GPU into impl_->scaled_tex first and
-                    // size the staging texture (and thus the CPU readback/memcpy)
-                    // to that smaller size instead of native resolution. Falls back
-                    // to the native-resolution path on any failure or when no
-                    // downscale is configured, so behavior is unchanged by default.
+                    // Downscale on the GPU before CPU readback; retain native readback if setup fails.
                     const uint32_t want_w = static_cast<uint32_t>(std::max(0, impl_->options.output_width));
                     const uint32_t want_h = static_cast<uint32_t>(std::max(0, impl_->options.output_height));
                     const bool want_scale = impl_->vp_available && want_w > 0 && want_h > 0 &&
diff --git a/libs/capture/capture.h b/libs/capture/capture.h
index 4a967c3..3122ed5 100644
--- a/libs/capture/capture.h
+++ b/libs/capture/capture.h
@@ -20,11 +20,7 @@ struct CaptureOptions {
     bool allow_unlimited_readback = false;
     HWND target_window = nullptr;
 
-    // Desired readback size. When both are > 0 and differ from the captured
-    // content size, the frame is downscaled on the GPU (D3D11 video
-    // processor) before the CPU staging readback, so readback/memcpy cost
-    // scales with the smaller output size instead of native resolution.
-    // 0 (default) = capture at native size, no GPU scaling step.
+    // Positive output dimensions request GPU downscale before readback; zero uses native size.
     int output_width = 0;
     int output_height = 0;
 };
@@ -42,10 +38,8 @@ struct FrameInfo {
     uint32_t height;
     uint32_t seq;           // monotonic, resets on start()
 
-    // CPU-readable BGRA pixel data via a D3D11 staging texture.
-    // Valid only for the duration of the callback; do not cache the pointer.
-    // nullptr on readback failure.  Stride >= width*4 (GPU row alignment).
-    // Spike path: GPU-encoder path (NVENC direct) is deferred to Milestone 4.
+    // BGRA storage is valid only during the callback; do not retain the pointer.
+    // A null pointer indicates readback failure; stride includes GPU row alignment.
     const uint8_t* bgra_data;
     uint32_t       bgra_stride;
 };
@@ -66,7 +60,7 @@ class DisplayCapture {
     DisplayCapture(const DisplayCapture&)            = delete;
     DisplayCapture& operator=(const DisplayCapture&) = delete;
 
-    // cb is invoked from the WGC thread pool - must be thread-safe.
+    // cb runs on the WGC thread pool; synchronize its shared state.
     // show_border = false requests yellow-border suppression via
     // GraphicsCaptureSession::IsBorderRequired(false); the OS may deny it.
     bool start(HMONITOR hmon, FrameCallback cb, bool show_border = false);
diff --git a/libs/disk-segments/disk_segments.cpp b/libs/disk-segments/disk_segments.cpp
index 1bf3e4a..935ec8e 100644
--- a/libs/disk-segments/disk_segments.cpp
+++ b/libs/disk-segments/disk_segments.cpp
@@ -313,9 +313,7 @@ bool DiskSegmentBuffer::save_clip(const std::wstring& out_dir, std::function<voi
             if (result.empty() && !path.empty()) {
                 std::error_code ec; fs::remove(path, ec);
                 if (ec) {
-                    // A failed output unlink is also owned/retryable. Refuse
-                    // further admissions/saves until it can be removed; never
-                    // delete its user-owned output directory.
+                    // Retain failed-output cleanup ownership and block admission until unlink succeeds.
                     auto& failed = failed_output;
                     failed->clip.path = std::move(path); failed->retained = false; failed->owns_parent = false;
                     failed->file_bytes = fs::file_size(failed->clip.path, ec);
diff --git a/libs/disk-segments/disk_segments.h b/libs/disk-segments/disk_segments.h
index c29ef64..4f4bbd0 100644
--- a/libs/disk-segments/disk_segments.h
+++ b/libs/disk-segments/disk_segments.h
@@ -9,15 +9,8 @@
 
 namespace disk_segments {
 
-// Rolling keyframe-aligned buffer of clip segments on disk - the "disk"
-// storage mode for the replay buffer. Mirrors replay_buffer::ReplayBuffer's
-// public surface so that class can route on its Config::storage. Segments are
-// ~5 s long (rolled on video keyframes); age and payload retention keep
-// the last Config::duration_sec behind the newest packet.
-//
-// Each segment is an independent, fully muxed file whose packets restart at
-// a common decode origin (composition/audio offsets preserved), for concat via
-// encoding::concat_clip_segments (which also trims the window edges).
+// Roll segments at video keys near five seconds. Each file uses a common decode
+// origin with composition/audio offsets for later concatenation.
 class DiskSegmentBuffer {
 public:
      DiskSegmentBuffer();
@@ -41,17 +34,12 @@ class DiskSegmentBuffer {
     void set_audio_params(encoding::AudioStreamParams const& p);
     void set_audio_params(std::vector<encoding::AudioStreamParams> const& p);
 
-    // Thread-safe - call from encoder sink callbacks.
+    // Encoder callbacks may push concurrently; serialize lifecycle changes.
     void push(encoding::EncodedPacket pkt);
 
-    // Concatenates the retained window [newest − duration, newest] into a
-    // clip in `out_dir` on a worker thread. cb runs on that thread with the
-    // output path (empty on failure / empty buffer). Concurrent calls are
-    // dropped (one save at a time), mirroring ReplayBuffer::save_clip:
-    // returns false when dropped (cb will not run in that case).
-    // cb may query stats/request another save (dropped), but must not clear
-    // or destroy this buffer from its own save thread. clear/destruction cancel
-    // cooperative FFmpeg I/O and join before releasing owned inputs.
+    // Save runs on a worker; an empty path reports failure. A rejected concurrent
+    // save returns false without invoking cb. The callback must not clear or destroy
+    // the buffer; teardown cancels I/O and joins the worker.
     bool save_clip(const std::wstring& out_dir,
                    std::function<void(std::wstring)> cb = nullptr);
 
diff --git a/libs/encoding/encoding.cpp b/libs/encoding/encoding.cpp
index 2913df0..092e746 100644
--- a/libs/encoding/encoding.cpp
+++ b/libs/encoding/encoding.cpp
@@ -44,7 +44,6 @@ static EncodedBytesRef make_encoded_bytes(const uint8_t* data, int size)
     return std::static_pointer_cast<const EncodedBytes>(mutable_bytes);
 }
 
-// ── probe_video_encoder ───────────────────────────────────────────────────────
 
 static const char* kEncoderCandidates[] = {
     "h264_nvenc", "h264_amf", "h264_qsv", "libx264",
@@ -70,8 +69,7 @@ static bool try_open_probe(const char* name, int width, int height)
     ctx->gop_size   = 60;
 
     AVDictionary* opts = nullptr;
-    // libx264/libx265 accept "ultrafast"; libaom-av1 does not (it has
-    // cpu-used instead), so leave it unset there.
+    // libaom-av1 uses cpu-used rather than an x264/x265 preset.
     if (strcmp(name, "libx264") == 0 || strcmp(name, "libx265") == 0)
         av_dict_set(&opts, "preset", "ultrafast", 0);
 
@@ -151,7 +149,6 @@ std::string resolve_video_encoder(const std::string& device,
     return first_openable({sw});
 }
 
-// ── VideoEncoder ──────────────────────────────────────────────────────────────
 
 struct VideoEncoder::Impl {
     std::mutex       mutex;
@@ -216,8 +213,7 @@ bool VideoEncoder::open(Config const& cfg, PacketSink sink)
     // mutating the caller's config.
     const int quality = (cfg.quality > 0)
         ? std::max(10, std::min(30, cfg.quality)) : 0;
-    // HW encoders (NVENC/QSV) refuse odd dimensions; align once here so the
-    // probe (which also aligns) and the real open agree on the frame size.
+    // Align output dimensions for hardware encoders.
     const int out_w = (cfg.width  + 1) & ~1;
     const int out_h = (cfg.height + 1) & ~1;
 
@@ -277,8 +273,7 @@ bool VideoEncoder::open(Config const& cfg, PacketSink sink)
         ctx->pix_fmt   = AV_PIX_FMT_YUV420P;
         ctx->flags    |= AV_CODEC_FLAG_GLOBAL_HEADER; // SPS/PPS in extradata
 
-        // Offline encodes (trim re-encode) want all cores; the live path keeps
-        // libavcodec defaults so capture latency is unchanged.
+        // Allow offline re-encoding to use all cores; live capture keeps codec thread defaults.
         if (is_sw && !cfg.low_latency)
             ctx->thread_count = 0; // auto
 
@@ -303,9 +298,7 @@ bool VideoEncoder::open(Config const& cfg, PacketSink sink)
                 av_dict_set_int(&opts, "crf", quality, 0);
             }
         } else {
-            // CBR: pin the average, ceiling and floor to the same target so the
-            // muxed file honours the exact bitrate the user picked, with a 1 s
-            // VBV buffer. Per-vendor RC hints keep HW encoders in true CBR.
+            // Set target/min/max bitrate together with a one-second VBV buffer.
             const int64_t br = cfg.bitrate;
             ctx->bit_rate     = br;
             ctx->rc_max_rate  = br;
@@ -337,10 +330,7 @@ bool VideoEncoder::open(Config const& cfg, PacketSink sink)
         }
 
         if (is_sw) {
-            // libx264/libx265 use "preset"/"tune"; libaom-av1 has neither
-            // (its speed knob is cpu-used), so only the x26x pair gets them.
-            // Offline encodes drop zerolatency (B-frames + frame threading:
-            // better quality per bit) and use a quality-leaning speed knob.
+            // Use codec-specific low-latency options; libaom-av1 has no x264 tune/preset.
             if (name == "libx264" || name == "libx265") {
                 av_dict_set(&opts, "preset",
                             cfg.low_latency ? "fast" : "medium", 0);
@@ -436,16 +426,11 @@ static void drain_video(ImplT* impl)
     }
 }
 
-// Shared tail of push_bgra/push_frame: stamp pts and hand the frame to the
-// encoder. Returns avcodec_send_frame's value. Caller holds the mutex.
-// (Templated like drain_video so it never names the private Impl type.)
+// Caller holds the mutex; submit the shared frame and return the codec status.
 template <typename ImplT>
 static int submit_current_frame(ImplT* impl, int64_t pts)
 {
-    // PTS: clock-locked frame index from the pacer (preferred), or fall back
-    // to the internal counter when pts < 0.  The pacer is the single source
-    // of timing truth - it emits exactly fps frames per real second (dup/skip),
-    // so this PTS advances at wall-clock rate.
+    // PTS is the supplied frame index or the next internal index when negative.
     if (pts >= 0) {
         impl->frame->pts = pts;
         impl->next_pts   = pts + 1;
@@ -560,7 +545,6 @@ void VideoEncoder::close()
     impl_->vsp      = {};
 }
 
-// ── AudioEncoder ──────────────────────────────────────────────────────────────
 
 struct AudioEncoder::Impl {
     std::mutex       mutex;
@@ -842,14 +826,7 @@ void AudioEncoder::close()
     impl_->asp           = {};
 }
 
-// ── TrackMixer ────────────────────────────────────────────────────────────────
-//
-// Canonical mix format is interleaved 32-bit float (AV_SAMPLE_FMT_FLT). Each
-// source owns a swr context (its native WASAPI format → canonical) plus a FIFO
-// of converted samples. A wall-clock-paced thread wakes every kMixIntervalMs,
-// computes how many output frames correspond to elapsed real time, sums that
-// many frames from every source (zero-filling sources that are behind), clips
-// to [-1, 1], and forwards the block to the sink.
+// Mix resampled sources on a wall-clock-paced worker; sources share one output track.
 
 namespace {
 constexpr int kMixIntervalMs   = 10;   // mix cadence
@@ -935,10 +912,7 @@ bool TrackMixer::open(int out_sample_rate, int out_channels, Sink sink)
             while (impl_->running.load(std::memory_order_acquire)) {
                 std::this_thread::sleep_for(std::chrono::milliseconds(kMixIntervalMs));
 
-                // Clock-locked CFR: the number of frames emitted is a function of the
-                // real time elapsed since `start`, not of loop iterations. Tracking a
-                // running total against a fixed origin avoids the cumulative drift of
-                // truncating per-tick deltas, keeping audio aligned over long sessions.
+                // Compute emitted frames from a fixed clock origin rather than accumulating rounded tick deltas.
                 int64_t elapsed_us =
                     std::chrono::duration_cast<std::chrono::microseconds>(
                         clock::now() - start).count();
@@ -976,9 +950,7 @@ bool TrackMixer::open(int out_sample_rate, int out_channels, Sink sink)
                     else if (v < -1.0f) v = -1.0f;
                 }
 
-                // Always emit, even when no source contributed (acc is then silence).
-                // A continuous output keeps every configured track present in the
-                // file and the downstream encoder timeline advancing at real time.
+                // Emit silence when no source contributes to keep the track clock advancing.
                 if (impl_->sink) {
                     impl_->sink(
                         reinterpret_cast<const uint8_t*>(acc.data()),
diff --git a/libs/encoding/encoding.h b/libs/encoding/encoding.h
index a162096..1c6d12a 100644
--- a/libs/encoding/encoding.h
+++ b/libs/encoding/encoding.h
@@ -10,12 +10,7 @@ struct AVFrame;
 
 namespace encoding {
 
-// Decodes the first frame of an existing video file and writes it as a PNG
-// thumbnail. The frame is scaled so its longest side is at most max_dim
-// (aspect ratio preserved). Returns true on success. Thread-safe: opens its
-// own demuxer/decoder/scaler and touches no shared state, so it is safe to
-// call from the async clip-save thread or a background reconcile thread.
-// Never call it from the UI/tray message loop (it does blocking decode I/O).
+// Blocking decode/PNG I/O: call off the UI thread. max_dim bounds the longest side.
 bool generate_thumbnail(const std::wstring& video_path,
                         const std::wstring& thumb_path,
                         int max_dim = 480);
@@ -86,12 +81,8 @@ std::string probe_video_encoder(int width, int height);
 // in probe order.  Used to populate the Settings UI encoder list.
 std::vector<std::string> available_video_encoders(int width, int height);
 
-// Resolves the user-facing choice (device: "gpu"/"cpu", codec: "h264"/"h265"/"av1")
-// to a concrete FFmpeg encoder name the current machine can actually open at
-// the given dimensions. GPU tries the vendor HW encoders (NVENC → AMF → QSV)
-// for the codec; CPU uses libx264/libx265/libaom-av1. If the preferred device
-// yields no working encoder, falls back to the other device for the same
-// codec. Returns "" if nothing opens.
+// Try the requested device, then the other device within the same codec family.
+// Return an empty name if no encoder opens.
 std::string resolve_video_encoder(const std::string& device,
                                    const std::string& codec,
                                    int width, int height);
@@ -103,7 +94,7 @@ struct VideoEncoderPerfStats {
     uint64_t encode_time_us_total = 0;
 };
 
-// H.264 encoder.  Not thread-safe - drive from a single thread (or serialise).
+// Serialize calls to the video encoder.
 class VideoEncoder {
 public:
      VideoEncoder();
@@ -116,20 +107,15 @@ class VideoEncoder {
         int     height = 0;          // output (encoded) height
         VideoCodec codec = VideoCodec::H264;
         int     fps     = 60;
-        // Rate control is always CBR at this target bitrate (bits per second).
-        // quality is retained only for probe/back-compat and is unused by the
-        // recorder path.
+        // bitrate is in bits per second; positive quality selects the legacy quality mode.
         int64_t bitrate = 20'000'000; // CBR target, bits/s
         int     quality = 0;          // 0 = CBR (default); >0 = legacy CQP/CRF
-        // Scaling filter (OBS-style): "bilinear", "bicubic", "lanczos".
-        // Used by sws_scale when capture and output resolutions differ.
         std::string scaling_filter = "bilinear";
         // "" or "auto" → probe NVENC → AMF → QSV → libx264.
         // Otherwise this encoder is tried first, then the probe order.
         std::string preferred_encoder;
-        // Extra AVOptions passed to avcodec_open2, "key=value:key=value"
-        // (also accepts ',' or ' ' between pairs).  If the encoder rejects
-        // them, open() retries without and extra_options_rejected() is set.
+        // Extra AVOptions use key=value pairs separated by colon, comma or space.
+        // Rejected options trigger a retry without extras and set extra_options_rejected.
         std::string extra_options;
         // Live capture keeps zerolatency tuning (no B-frames, fast presets).
         // Offline re-encode (quick trim) clears this for better quality per
@@ -140,21 +126,13 @@ class VideoEncoder {
     // Open codec.  sink receives encoded packets (called synchronously).
     bool open(Config const& cfg, PacketSink sink);
 
-    // Encode one BGRA frame.  bgra must be valid for the duration of the call.
-    // stride = bytes per row (>= width*4 after GPU-alignment).
-    // Frames are scaled to the configured output width/height when the
-    // source dimensions differ.
-    // pts: frame index in the encoder timebase (1/fps).  Must be supplied by
-    // a clock-locked CFR pacer so playback speed matches wall-clock.  Pass -1
-    // to fall back to the internal auto-increment counter (legacy behaviour).
+    // BGRA storage must remain valid during the call; stride includes row padding.
+    // PTS is a frame index in 1/fps; -1 selects internal incrementing timestamps.
     void push_bgra(const uint8_t* bgra, int stride, int width, int height,
                    int64_t pts = -1);
 
-    // Encode one decoded frame directly (e.g. YUV420P from a demuxer).  When
-    // the frame already matches the encoder's pixel format and output size
-    // the planes are shared - no BGRA round-trip, no extra quality loss.
-    // Otherwise the frame is converted/scaled like push_bgra would.
-    // pts semantics as in push_bgra.
+    // Matching format/size shares the decoded planes; other input is converted.
+    // PTS follows push_bgra semantics.
     void push_frame(const AVFrame* frame, int64_t pts = -1);
 
     void flush();
@@ -210,18 +188,11 @@ class AudioEncoder {
     Impl* impl_;
 };
 
-// Mixes PCM from multiple capture sources into a single output stream for one
-// audio track. Each source is resampled to a canonical format and buffered;
-// an internal wall-clock-paced thread sums all sources (with clipping) and
-// emits a steady output stream through the sink, so the downstream encoder
-// timeline advances at real-time rate regardless of per-source bursts/gaps.
-//
-// Used only when two or more sources are routed to the same track; a single
-// source still feeds its encoder directly without going through the mixer.
+// Resample sources to one track and emit wall-clock-paced float PCM.
+// Use direct encoder input when a track has only one source.
 class TrackMixer {
 public:
-    // Sink receives mixed PCM in the canonical format (interleaved float).
-    // Signature mirrors AudioEncoder::push_pcm so it can forward directly.
+    // Sink PCM is interleaved float in the configured output format.
     using Sink = std::function<void(const uint8_t* data, int bytes,
                                     int sample_rate, int channels,
                                     int bit_depth, bool is_float)>;
@@ -234,22 +205,17 @@ class TrackMixer {
     // Starts the mix thread. out_channels is the canonical channel count.
     bool open(int out_sample_rate, int out_channels, Sink sink);
 
-    // Registers a source and returns its id (>= 0), or -1 if not open.
-    // Thread-safe. Optional linear gain (0.0-1.0+) applied to this source's
-    // samples before they are summed into the mix.
+    // Gain is linear; negative/nonfinite input is muted. Return -1 when registration fails.
     int add_source(float gain = 1.0f);
 
-    // Updates a source's linear gain. Thread-safe; no-op for unknown ids.
     void set_source_gain(int source_id, float gain);
 
-    // Removes a previously added source. Thread-safe.
     void remove_source(int source_id);
 
     // Number of currently registered sources.
     int source_count() const;
 
-    // Feeds PCM for one source. Converts to the canonical format and buffers it.
-    // Safe to call from that source's capture thread; data need not outlive call.
+    // Copy/convert PCM during the call; the caller retains input ownership.
     void push(int source_id, const uint8_t* data, int bytes,
               int sample_rate, int channels, int bit_depth, bool is_float);
 
diff --git a/libs/encoding/mux_common.cpp b/libs/encoding/mux_common.cpp
index 7f936ab..6032169 100644
--- a/libs/encoding/mux_common.cpp
+++ b/libs/encoding/mux_common.cpp
@@ -123,12 +123,7 @@ bool open_file_and_write_header(AVFormatContext* fmt,
     if (avio_open(&fmt->pb, path_utf.c_str(), AVIO_FLAG_WRITE) < 0)
         return false;
 
-    // NB: no "+faststart" for mp4. faststart relocates the moov atom to the
-    // front of the file at av_write_trailer() time, which rewrites the ENTIRE
-    // file on stop - for a multi-GB manual recording that is many seconds of
-    // disk/CPU on the calling thread and froze the UI/hotkeys. We instead leave
-    // the moov at the end (OBS default); local playback and editing are
-    // unaffected, and finalizing only writes the index, so stop is near-instant.
+    // Omit faststart to avoid rewriting a large MP4 during stop; moov remains at the end.
     const bool ok = avformat_write_header(fmt, nullptr) >= 0;
     if (!ok) {
         // avformat_free_context does not close pb - callers that only free the
diff --git a/libs/encoding/mux_common.h b/libs/encoding/mux_common.h
index f3a788e..f39a4d1 100644
--- a/libs/encoding/mux_common.h
+++ b/libs/encoding/mux_common.h
@@ -30,10 +30,7 @@ struct StreamSet {
     std::array<AVStream*, 7> audio{};
 };
 
-// Allocates an output AVFormatContext for `path_utf` using the container's muxer
-// and creates the video stream plus one stream per valid audio param.  On success
-// *out_fmt holds the context and *out_streams the stream mapping; returns false
-// (and frees any partial context) on failure.
+// On success the caller owns out_fmt; failure releases the partial context.
 bool alloc_output(const std::string&                          path_utf,
                   const std::string&                          container,
                   const VideoStreamParams&                    vsp,
@@ -41,17 +38,12 @@ bool alloc_output(const std::string&                          path_utf,
                   AVFormatContext**                           out_fmt,
                   StreamSet*                                  out_streams);
 
-// Opens the file and writes the container header. mp4 keeps the moov atom at the
-// end (no +faststart) so finalizing never rewrites the whole file on stop.
-// On failure the io context is closed here (avformat_free_context alone does
-// not release it), so callers only need to free the context.
+// Close AVIO on header failure; the caller must still free the format context.
 bool open_file_and_write_header(AVFormatContext* fmt,
                                 const std::string& path_utf,
                                 const std::string& container);
 
-// Builds "<dir>\<yyyymmdd_hhmmss_mmm>_<N>s_clip.<ext>" from local time. The
-// millisecond field keeps two saves issued within the same second from
-// overwriting each other. Safe for long directories (no fixed-size buffer).
+// Use local time including milliseconds for the clip filename.
 std::wstring generate_clip_path(const std::wstring& dir,
                                 int duration_sec,
                                 const std::string& container);
@@ -65,17 +57,12 @@ bool write_packet(AVFormatContext* fmt,
                   int64_t          pts_offset,
                   int64_t          dts_offset);
 
-// Captures the pts/dts of the first packet observed on a stream, so callers
-// can offset every subsequent packet back to zero. Shared by both mux modes:
-// replay-buffer's one-shot snapshot (anchor only, never reset) and manual
-// recording's continuous-with-pause stream (anchor plus caller-tracked pause
-// accumulation added on top of anchor.pts/anchor.dts).
+// Observe a timestamp pair once and retain it as the mux offset origin.
 struct TimingAnchor {
     bool    set = false;
     int64_t pts = 0;
     int64_t dts = 0;
 
-    // No-op after the first call for this instance.
     void observe(int64_t p, int64_t d)
     {
         if (set) return;
diff --git a/libs/encoding/thumbnail.cpp b/libs/encoding/thumbnail.cpp
index 1823dd6..29b9817 100644
--- a/libs/encoding/thumbnail.cpp
+++ b/libs/encoding/thumbnail.cpp
@@ -31,7 +31,6 @@ namespace {
 
 using platform_win::wide_to_utf8;
 
-// RAII wrappers so early returns can't leak libav objects.
 struct FmtCtx {
     AVFormatContext* p = nullptr;
     ~FmtCtx() { if (p) avformat_close_input(&p); }
@@ -137,7 +136,6 @@ bool generate_thumbnail(const std::wstring& video_path,
     }
     if (!got || decoded.p->width <= 0 || decoded.p->height <= 0) return false;
 
-    // Scale so the longest side is at most max_dim (aspect preserved, even dims).
     const int sw = decoded.p->width, sh = decoded.p->height;
     double scale = std::min(1.0, static_cast<double>(max_dim) / std::max(sw, sh));
     int dw = std::max(2, (static_cast<int>(sw * scale) / 2) * 2);
diff --git a/libs/encoding/trim.cpp b/libs/encoding/trim.cpp
index 03b5020..f47a27d 100644
--- a/libs/encoding/trim.cpp
+++ b/libs/encoding/trim.cpp
@@ -66,10 +66,8 @@ int64_t packet_duration(const AVPacket* p, AVStream* s) {
     const AVRational rate = s->avg_frame_rate;
     return rate.num > 0 && rate.den > 0 ? std::max<int64_t>(1, av_rescale_q(1, av_inv_q(rate), s->time_base)) : 1;
 }
-// Matroska omits leading decode timestamps for reordered video. Recover only
-// from the next known DTS by subtracting the intervening packet durations in
-// the SAME input timebase. Never clamp DTS to PTS or fabricate a CFR timeline.
-// Unresolvable/malformed prefixes fail explicitly rather than grow a queue.
+// Recover missing leading Matroska DTS from packet durations in the input timebase.
+// Reject unresolved prefixes rather than synthesizing a frame-rate timeline.
 struct TimestampReader {
     AVFormatContext* in;
     std::deque<AVPacket*> pending;
@@ -415,10 +413,8 @@ bool concat_clip_segments(const std::vector<ClipSegment>& segs, double start, do
             opened = true; global_anchor = actual_start;
         } else if (!same_layout(first.p, first_order, in.p, order)) return fail(err, "segments have incompatible stream parameters");
         const double offset = actual_start - global_anchor;
-        // Segment ownership changes at video DTS, not its delayed presentation
-        // timestamp. Applying each key's PTS as a fresh audio trim drops AAC at
-        // every B-frame GOP boundary. Only the outer start uses the retained
-        // presentation anchor; internal audio uses the common source timeline.
+        // Internal segment ownership changes at video DTS. Use the common audio
+        // timeline across GOP boundaries and the presentation anchor only at the outer cut.
         const double local_origin = static_cast<double>(origin(in.p)) / AV_TIME_BASE;
         const double audio_start = first_segment ? seconds(w.anchor, w.tb)
             : seg.file_origin_seconds + local_origin;
diff --git a/libs/encoding/trim.h b/libs/encoding/trim.h
index 54ffdf1..563eb0b 100644
--- a/libs/encoding/trim.h
+++ b/libs/encoding/trim.h
@@ -22,17 +22,13 @@ struct TrimResult {
         return std::nullopt;
     }
 };
-// Lossless is keyframe-aware, not exact: preceding keyframe and required
-// reordered reference packets can extend the requested interval. Audio is
-// copied at packet boundaries, with its original offset, not sample-trimmed.
-// Results describe the retained timeline; failed output is removed by caller.
+// Lossless cuts include reference/keyframe preroll. Audio keeps packet boundaries
+// and offsets; TrimResult describes the retained interval.
 bool trim_clip_lossless(const std::wstring& path, double start, double end,
                         const std::wstring& out_path, std::string* err,
                         TrimResult* result = nullptr);
-// Explicit same-video-codec software fallback. Decode preroll, filter decoded
-// frame timestamps, preserve VFR/timebase and copy ALL audio tracks unchanged.
-// Unsupported encoder/pixel format/container fails; never substitutes a codec
-// or silently drops audio. No packet vectors proportional to clip duration.
+// Re-encode in the same codec, retaining VFR and copying all audio tracks.
+// Unsupported format/encoder/container returns failure.
 bool trim_clip_reencode(const std::wstring& path, double start, double end,
                         const std::wstring& out_path, std::string* err,
                         TrimResult* result = nullptr);
diff --git a/libs/gamelist/gamelist.cpp b/libs/gamelist/gamelist.cpp
index ca6f025..f337ccd 100644
--- a/libs/gamelist/gamelist.cpp
+++ b/libs/gamelist/gamelist.cpp
@@ -43,13 +43,10 @@ constexpr INTERNET_PORT kPort = INTERNET_DEFAULT_HTTPS_PORT;
 constexpr std::time_t kRefreshSeconds = 72 * 60 * 60;
 constexpr std::time_t kEmptyRetrySeconds = 60 * 60;
 
-// A real response has thousands of entries; anything tiny is treated as a bad
-// fetch and must never overwrite a good DB.
+// Reject undersized responses before replacing the cached database.
 constexpr size_t kMinPlausibleEntries = 50;
 
-// Bump when the `games` table layout changes so old DBs are rebuilt. v1 keyed on
-// exe_lower alone (one game per exe); v2 allows many games per exe (composite key
-// exe_lower+discord_app_id) so shared executables like javaw.exe keep every game.
+// Schema v2 keys by (exe_lower, discord_app_id) to retain shared-executable games.
 constexpr int kSchemaVersion = 2;
 
 std::function<void(const char*, const char*)> g_log_sink;
@@ -60,7 +57,6 @@ void log_msg(const char* tag, const std::string& msg)
     OutputDebugStringA(("[gamelist] " + msg + "\n").c_str());
 }
 
-// ── Shared state ────────────────────────────────────────────────────────────
 
 std::mutex                       g_snapshot_mutex;
 std::shared_ptr<const GameMap>   g_snapshot = std::make_shared<const GameMap>();
@@ -79,7 +75,6 @@ void publish(std::shared_ptr<const GameMap> map)
     g_snapshot = std::move(map);
 }
 
-// ── SQLite ──────────────────────────────────────────────────────────────────
 
 bool exec(sqlite3* db, const char* sql)
 {
@@ -120,8 +115,7 @@ sqlite3* open_db()
         return nullptr;
     }
 
-    // Migrate on schema change: drop a stale `games` table so it is recreated
-    // with the current layout (and re-synced from the network on the next tick).
+    // Recreate an outdated table and schedule network repopulation.
     int stored_version = 0;
     {
         sqlite3_stmt* vs = nullptr;
@@ -236,7 +230,6 @@ bool write_games(sqlite3* db, const GameMap& map, std::time_t now)
     return exec(db, "COMMIT;");
 }
 
-// ── HTTP ────────────────────────────────────────────────────────────────────
 
 bool http_get(std::string* body)
 {
@@ -292,14 +285,10 @@ bool http_get(std::string* body)
     return ok;
 }
 
-// ── Parse ───────────────────────────────────────────────────────────────────
 
 std::string basename_lower(const std::string& name)
 {
-    // Discord marks some executables with a leading '>' - the game runs as a
-    // child/launched process rather than the top-level exe (e.g. Minecraft is
-    // listed as ">javaw.exe"). Strip that marker so the key is the real process
-    // basename we can match against a running process.
+    // Strip Discord executable markers and retain Windows platform entries.
     size_t start = 0;
     while (start < name.size() && (name[start] == '>' || name[start] == ' '))
         ++start;
@@ -329,8 +318,7 @@ bool parse_detectables(const std::string& json, GameMap* out)
         for (const auto& exe : *exes) {
             if (!exe.is_object()) continue;
             if (exe.value("os", std::string()) != "win32") continue;
-            // Skip bare launchers (Steam/Epic/etc.) so we detect the game, not
-            // the storefront that started it.
+            // Exclude launchers from detection membership.
             if (exe.value("is_launcher", false)) continue;
             const std::string raw = exe.value("name", std::string());
             if (raw.empty()) continue;
@@ -441,8 +429,7 @@ void init(const std::wstring& app_data_dir)
     g_started = true;
     g_db_path = app_data_dir + L"\\game_list.db";
 
-    // Load whatever we already have synchronously so detection has data on the
-    // first tick even before the network sync completes.
+    // Load the local snapshot before starting network refresh.
     if (sqlite3* db = open_db()) {
         auto loaded = load_from_db(db);
         if (!loaded->empty())
diff --git a/libs/gamelist/gamelist.h b/libs/gamelist/gamelist.h
index 65aea6f..e4d566f 100644
--- a/libs/gamelist/gamelist.h
+++ b/libs/gamelist/gamelist.h
@@ -6,21 +6,8 @@
 #include <unordered_map>
 #include <vector>
 
-// Local, DB-backed Discord game list. Detection is gated on membership in this
-// list: a running process is only treated as a "game" when its executable
-// basename appears here. Owned by the recorder engine so detection works
-// headless (no UI process required).
-//
-// Source: the Discord public detectable endpoint
-//   https://discord.com/api/v10/applications/detectable
-// which returns the games/apps Discord recognizes, each with the executable
-// name(s) that identify it. We keep the win32 executables mapped to the entry's
-// display name and Discord application id.
-//
-// Persisted to %LocalAppData%\Monolith\game_list.db. Refreshed on startup, then
-// every 72h (and immediately if the DB is missing/empty at check time). All
-// network + disk work happens on a background worker thread; readers only touch
-// an in-memory snapshot, so the tray/UI message loop never blocks.
+// Detection uses a local Discord-derived database. Refresh it separately from
+// process polling; records may share an executable basename.
 namespace gamelist {
 
 struct GameEntry {
@@ -40,13 +27,10 @@ using GameMap = std::unordered_map<std::string, GameList>;
 // failures into its own always-on error log. Set once before init().
 void set_log_sink(std::function<void(const char* tag, const char* msg)> sink);
 
-// Loads the on-disk DB into memory and starts the refresh worker. `app_data_dir`
-// is %LocalAppData%\Monolith (resolved by the caller). Safe to call once.
+// Initialize once; app_data_dir is supplied by the host.
 void init(const std::wstring& app_data_dir);
 
-// O(1), lock-free-for-readers snapshot of the current map. Never blocks on disk
-// or network - this is what the detection poll calls every tick. May be empty
-// before the first successful sync.
+// Read the current in-memory snapshot; it may be empty before initial sync.
 std::shared_ptr<const GameMap> snapshot();
 
 // Convenience membership test against the current snapshot.
diff --git a/libs/ipc/ipc_server.cpp b/libs/ipc/ipc_server.cpp
index 1324a24..537cb0b 100644
--- a/libs/ipc/ipc_server.cpp
+++ b/libs/ipc/ipc_server.cpp
@@ -122,8 +122,7 @@ void handle_client(SOCKET client)
         const int n = recv(client, tmp, static_cast<int>(sizeof(tmp)), 0);
         if (n == SOCKET_ERROR && WSAGetLastError() == WSAEWOULDBLOCK) continue;
         if (n <= 0) return;
-        // Process bytes by explicit length: embedded NUL is invalid JSON, not
-        // a C-string terminator. Never accumulate an unbounded pipelined batch.
+        // Use byte lengths; embedded NUL remains invalid JSON. Bound pipelined input.
         for (int i = 0; i < n && g_running; ++i) {
             if (tmp[i] != '\n') {
                 if (buf.size() == detail::kMaxRequestBytes) return;
@@ -163,11 +162,7 @@ void handle_client(SOCKET client)
                         PostMessage(g_hwnd, WM_COMMAND, MAKEWPARAM(kCmdPauseResume, 0), 0);
                         response = make_result(req_id, {{"status", "accepted"}});
                     } else if (method == "get_status") {
-                        // g_status_fn/g_mutation_fn are set once in start() before the
-                        // accept loop begins and never reassigned, so concurrent
-                        // handle_client() threads reading them is safe without a lock.
-                        // Each call reads live engine state (g_recording, etc.), which
-                        // is independently synchronized by its own owner.
+                        // Callbacks are installed before accepting clients; their own state needs synchronization.
                         RecordingState st = g_status_fn();
                         response = make_result(req_id, {
                             {"recording",         st.is_recording},
@@ -181,11 +176,7 @@ void handle_client(SOCKET client)
                         PostMessage(g_hwnd, kMsgSettingsReload, 0, 0);
                         response = make_result(req_id, {{"status", "accepted"}});
                     } else if (method == "update_close_ui") {
-                        // Updater.exe asks the engine to close the UI process
-                        // so ui\* can be swapped on disk. Runs directly on
-                        // this IPC thread (blocks up to ~3s: graceful close,
-                        // then terminate) - the reply is the confirmation
-                        // that the files are safe to replace.
+                        // Block this IPC thread until the UI exits before allowing file replacement.
                         if (!g_update_close_ui_fn) {
                             response = make_error(req_id, -32601, "Update control unavailable");
                         } else {
@@ -193,18 +184,11 @@ void handle_client(SOCKET client)
                             response = make_result(req_id, {{"status", "ok"}});
                         }
                     } else if (method == "update_engine_exit") {
-                        // Updater.exe asks the engine to shut down so the
-                        // engine files can be swapped. Graceful by design:
-                        // WM_CLOSE → WM_DESTROY stops any recording cleanly.
-                        // The reply may never arrive (the engine tears its
-                        // IPC server down during shutdown) - the updater
-                        // polls for the port to close instead.
+                        // Post engine shutdown; the updater confirms port closure because the reply may be lost.
                         PostMessage(g_hwnd, WM_CLOSE, 0, 0);
                         response = make_result(req_id, {{"status", "accepted"}});
                     } else if (method == "recording_add_bookmark") {
-                        // Handled directly on the IPC thread: bookmark timestamp
-                        // accuracy matters, so it must not round-trip through the
-                        // message loop.
+                        // Timestamp bookmarks on this IPC thread, before message-loop latency.
                         if (!g_add_bookmark_fn) {
                             response = make_error(req_id, -32601, "Bookmark handler unavailable");
                         } else {
@@ -259,11 +243,7 @@ void handle_client(SOCKET client)
                             m.title    = get_or("title", std::string());
                             m.start    = get_or("start", 0.0);
                             m.end      = get_or("end", 0.0);
-                            // handle_client runs on its own thread per connection; the
-                            // mutation callback (handle_clip_mutation in main.cpp)
-                            // opens its own DB handle per call and only touches
-                            // mutex-guarded globals, so concurrent invocations from
-                            // different client threads are safe.
+                            // Mutation callbacks run concurrently on different client threads.
                             std::string err = g_mutation_fn(m);
                             if (err.empty())
                                 response = make_result(req_id, {{"status", "ok"}});
@@ -290,8 +270,7 @@ void handle_client(SOCKET client)
 void accept_loop(SOCKET server)
 {
     while (g_running) {
-        // Poll even without new connections so the last completed worker is
-        // reclaimed promptly, not merely at the next accept or at shutdown.
+        // Reclaim completed workers even without a new connection.
         for (auto it = g_clients.begin(); it != g_clients.end();) {
             if ((*it)->done.load()) {
                 (*it)->thread.join();
diff --git a/libs/ipc/ipc_server.h b/libs/ipc/ipc_server.h
index 59c382a..46d33fc 100644
--- a/libs/ipc/ipc_server.h
+++ b/libs/ipc/ipc_server.h
@@ -11,22 +11,13 @@ struct RecordingState {
     bool is_paused;
     bool replay_enabled;
     bool recording_enabled;
-    // Monotonically increasing counter bumped each time a clip is cataloged
-    // (replay save or manual-recording stop). The UI host polls get_status and
-    // pushes a live refresh to the webview whenever this value changes, so
-    // the clip library updates in real time without an app restart.
+    // UI hosts poll this catalog generation to request a library refresh.
     uint64_t clip_generation = 0;
-    // Engine component version (MONOLITH_VERSION_STRING). Surfaced through
-    // get_status so the Settings UI can show engine + interface versions
-    // side by side - the two are versioned independently.
+    // Engine and interface component versions are independent.
     std::string version;
 };
 
-// A UI-driven mutation of a clip catalog row. Dispatched to the recorder (the
-// single writer) so the UI never writes the DB concurrently. `method` is one of:
-// "clip_set_favorite", "clip_add_hashtag", "clip_remove_hashtag", "clip_rename",
-// "clip_set_title", "clip_delete", "clip_trim". `source` picks the DB
-// ("replay" -> clips.db, "manual" -> recs.db).
+// Mutation source selects clips.db or recs.db. Callbacks run on IPC threads.
 struct ClipMutation {
     std::string method;
     std::string source;   // "replay" | "manual"
@@ -42,40 +33,18 @@ struct ClipMutation {
 // Returns "" on success, or a human-readable error message on failure.
 using ClipMutationFn = std::function<std::string(const ClipMutation&)>;
 
-// Adds a bookmark at the current recording position of the running manual
-// recording. Called on an IPC client thread (timestamp accuracy matters, so it
-// must NOT round-trip through the message loop). Returns "" on success or an
-// error message ("not recording", "recording is paused", ...).
+// Timestamp bookmarks on the IPC thread; return an empty string or an error.
 using AddBookmarkFn = std::function<std::string()>;
 
-// UI-driven selection of which detected game to record/clip when several are
-// running. `exe` is the lowercased executable basename (stable across restarts);
-// `pid` is an optional live hint. Empty exe + pid 0 clears the selection (auto).
-// Called on an IPC client thread - the handler must only touch synchronized
-// state and defer engine work to the message loop.
+// An empty exe and zero PID clears selection. Defer engine work to the message loop.
 using SelectGameFn = std::function<void(const std::string& exe, uint32_t pid)>;
 
-// Closes the running Monolith.UI process so Updater.exe can swap ui\* on
-// disk. Called on an IPC client thread by update_close_ui; blocks until the
-// UI has exited (graceful close, then terminate after a timeout) exactly
-// like the engine's own shutdown path.
+// Block the IPC worker until UI exit, with graceful close then forced termination.
 using UpdateCloseUiFn = std::function<void()>;
 
-// Start the JSON-RPC TCP server on 127.0.0.1:45991.
-// Bounded at 16 clients, 64 KiB per line (excluding LF), JSON depth 64.
-// Excess clients/oversized lines are disconnected. Partial lines and response
-// sends have 30s total deadlines; idle persistent clients have NO idle timeout.
-// start/stop serialize lifecycle; callbacks must not call start/stop themselves.
-// stop interrupts socket I/O but still waits for in-flight callbacks to return.
-// Recording commands (save_replay, recording_start/stop, pause_resume) are
-// dispatched via PostMessage to hwnd. `status_fn` answers get_status and
-// `mutation_fn` performs clip_* mutations; both may be called concurrently
-// from multiple client-handler threads and must be internally thread-safe.
-// `select_fn` handles set_selected_game. `add_bookmark_fn` handles
-// recording_add_bookmark directly on the IPC thread. `update_close_ui_fn`
-// handles update_close_ui (blocks until the UI process is gone).
-// `reload_settings` posts WM_APP+2 to hwnd; `update_engine_exit` posts
-// WM_CLOSE to hwnd (graceful shutdown - stops any recording first).
+// Server limits: 16 clients, 64 KiB lines, JSON depth 64 and 30 s I/O deadlines.
+// Callbacks can run concurrently and must not call start/stop. stop interrupts
+// socket I/O and waits for callbacks; idle clients have no timeout.
 void start(HWND hwnd,
            std::function<RecordingState()> status_fn,
            ClipMutationFn mutation_fn = nullptr,
diff --git a/libs/logging/logging.cpp b/libs/logging/logging.cpp
index 3bbc788..7ec9a63 100644
--- a/libs/logging/logging.cpp
+++ b/libs/logging/logging.cpp
@@ -126,8 +126,7 @@ void log_error(const char* tag, const char* msg)
         st.wHour, st.wMinute, st.wSecond,
         tag, msg);
 
-    // Always surfaced: to the debugger, and to the log file - opened on demand
-    // even when verbose logging is disabled - so failures aren't silent.
+    // Error records bypass verbose logging and may open the log file.
     OutputDebugStringA(buf);
     if (!g_file) open_locked();
     if (g_file) { fputs(buf, g_file); fflush(g_file); }
diff --git a/libs/logging/logging.h b/libs/logging/logging.h
index 8a11eff..39c35bd 100644
--- a/libs/logging/logging.h
+++ b/libs/logging/logging.h
@@ -2,10 +2,7 @@
 
 #include <string>
 
-// Rotating file logger for the recorder engine. Disabled by default - no log
-// file is created and log() is a cheap no-op - until the user opts in via
-// Settings > Advanced (advanced.logging_enabled), wired through set_enabled()
-// on settings reload.
+// Verbose logging is opt-in; error logging has a separate always-on path.
 namespace logging {
 
 // Call once at startup. `dir` is the directory the log file lives in
@@ -13,19 +10,13 @@ namespace logging {
 // main.cpp) since other subsystems need that path too.
 void init(bool enabled, const std::wstring& dir);
 
-// Toggles logging at runtime (settings reload). Opens or closes the log file
-// to match; safe to call repeatedly, including with the same value.
 void set_enabled(bool enabled);
 
 bool enabled();
 
 void log(const char* tag, const char* msg);
 
-// Always-on error channel. Unlike log(), this is NOT gated by enabled(): the
-// message is emitted to the debugger and appended to the log file (opened on
-// demand even when verbose logging is off) so genuine failures are never
-// silent. Reserve for real errors - it bypasses the opt-in and can create the
-// log file.
+// Error logging bypasses enabled() and opens the file on demand.
 void log_error(const char* tag, const char* msg);
 
 } // namespace logging
diff --git a/libs/replay-buffer/replay_buffer.cpp b/libs/replay-buffer/replay_buffer.cpp
index de48d37..2e136b7 100644
--- a/libs/replay-buffer/replay_buffer.cpp
+++ b/libs/replay-buffer/replay_buffer.cpp
@@ -33,7 +33,6 @@ namespace replay_buffer {
 
 namespace mux = encoding::mux;
 
-// ── Impl ──────────────────────────────────────────────────────────────────────
 
 struct ReplayBuffer::Impl : detail::PacketRing {
     mutable std::mutex              mutex;
@@ -51,7 +50,6 @@ struct ReplayBuffer::Impl : detail::PacketRing {
     std::thread                     save_thread;
 };
 
-// ── ReplayBuffer ──────────────────────────────────────────────────────────────
 
 ReplayBuffer::ReplayBuffer()  : impl_(new Impl()) {}
 ReplayBuffer::~ReplayBuffer()
@@ -173,7 +171,6 @@ ReplayBufferStats ReplayBuffer::stats() const
     return s;
 }
 
-// ── Clip save internals ───────────────────────────────────────────────────────
 
 static std::wstring generate_clip_path(const std::wstring& dir, int duration_sec,
                                        const std::string& container)
@@ -199,13 +196,11 @@ static std::wstring write_clip(
     std::string  path_utf = mux::wcs_to_utf8(path);
     if (path_utf.empty()) return {};
 
-    // ── Reorder packets by DTS (OBS-style: B-frame safety) ──────────────────
     std::stable_sort(pkts.begin(), pkts.end(),
         [](const encoding::EncodedPacket& a, const encoding::EncodedPacket& b) {
             return a.dts_usec < b.dts_usec;
         });
 
-    // ── Open output context + streams ───────────────────────────────────────
     AVFormatContext* fmt = nullptr;
     mux::StreamSet streams;
     if (!mux::alloc_output(path_utf, container, vsp, audio_params, &fmt, &streams))
@@ -224,7 +219,6 @@ static std::wstring write_clip(
     const auto& key = pkts.front();
     const AVRational anchor_tb{key.tb_num, key.tb_den};
 
-    // ── Write packets (already in DTS order) ─────────────────────────────────
     for (const auto& ep : pkts) {
         AVStream* dst_stream = nullptr;
         if (ep.stream_index == 0)
@@ -254,7 +248,6 @@ static std::wstring write_clip(
     return path;
 }
 
-// ── save_clip ─────────────────────────────────────────────────────────────────
 
 void ReplayBuffer::save_clip(std::function<void(std::wstring)> cb)
 {
@@ -264,12 +257,7 @@ void ReplayBuffer::save_clip(std::function<void(std::wstring)> cb)
         return;
 
     try {
-    // Disk mode: hand off to the segment buffer (it owns its own save
-    // thread); the facade's saving flag mirrors it so stats() stays honest.
-    // Read cfg/disk under the lock - configure() can swap storage modes and
-    // reset the disk buffer concurrently (settings reload thread). RAM mode
-    // (disk == nullptr, the normal configuration) falls through to the
-    // snapshot path below.
+    // Hold the config lock while routing to the disk buffer; configure can replace it.
     {
         std::lock_guard lk(impl_->mutex);
         if (impl_->disk) {
diff --git a/libs/replay-buffer/replay_buffer.h b/libs/replay-buffer/replay_buffer.h
index b400490..3decfab 100644
--- a/libs/replay-buffer/replay_buffer.h
+++ b/libs/replay-buffer/replay_buffer.h
@@ -8,9 +8,7 @@
 
 namespace replay_buffer {
 
-// Thread-safe rolling ring buffer over EncodedPackets.
-// push() is safe to call concurrently from multiple threads.
-// save_clip() snapshots the buffer and writes a clip file asynchronously.
+// Serialize lifecycle changes; push/save use synchronized packet state.
 struct ReplayBufferStats {
     size_t packet_count = 0;
     // RAM: retained encoded payload only, excluding bounded packet/index
@@ -53,7 +51,7 @@ class ReplayBuffer {
     void set_audio_params(encoding::AudioStreamParams const& p);
     void set_audio_params(std::vector<encoding::AudioStreamParams> const& p);
 
-    // Thread-safe - call from encoder sink callbacks.
+    // Encoder callbacks may push concurrently; serialize lifecycle changes.
     void push(encoding::EncodedPacket pkt);
 
     // Snapshot the ring buffer and save a clip asynchronously.
diff --git a/libs/storage/storage.cpp b/libs/storage/storage.cpp
index 270488e..3992808 100644
--- a/libs/storage/storage.cpp
+++ b/libs/storage/storage.cpp
@@ -165,8 +165,6 @@ std::string now_iso8601_utc() {
   return buf;
 }
 
-// ── Settings KV store
-// ──────────────────────────────────────────────────────────
 
 namespace {
 
@@ -275,10 +273,8 @@ bool settings_replace_all(
   return ok;
 }
 
-// ── Durable file mutations ─────────────────────────────────────────────────
-// SQLite and filesystem renames cannot share one atomic transaction.  The
-// journal records only leaf names and exact quarantine names so recovery can
-// compensate a prepared operation without guessing at arbitrary paths.
+// Filesystem moves and SQLite cannot share one transaction. Journal exact
+// leaf/quarantine names for recovery compensation.
 namespace {
 struct Mutation {
   std::string token, op, stage;
@@ -479,8 +475,6 @@ bool delete_clip_rows(sqlite3 *db, int64_t id, std::string *error) {
 }
 } // namespace
 
-// ── Impl
-// ───────────────────────────────────────────────────────────────────────
 
 struct ClipDb::Impl {
   sqlite3 *db = nullptr;
diff --git a/libs/storage/storage.h b/libs/storage/storage.h
index da70a72..b64edd3 100644
--- a/libs/storage/storage.h
+++ b/libs/storage/storage.h
@@ -6,18 +6,8 @@
 #include <utility>
 #include <vector>
 
-// libs/storage - SQLite-backed clip catalog co-located with each output folder.
-//
-// Layout (auto-contained per output folder chosen in Settings > Output):
-//   <folder>\clips.db   (source "replay")   or   <folder>\recs.db (source "manual")
-//   <folder>\*.mp4|*.mkv                     (the video files, written as before)
-//   <folder>\.thumbs\<base>.png              (first-frame thumbnails)
-//
-// The recorder (the always-on process) is the single writer at clip-save time
-// and for reconcile. UI-driven mutations (favorite/hashtag/delete) also route
-// through the recorder over IPC so there is exactly one writer per DB. The UI
-// process opens the same DB read-only for the grid. All connections use WAL +
-// busy_timeout so reads never block the writer.
+// Each output folder holds its source catalog and .thumbs directory.
+// Paths in rows are relative to that folder.
 
 namespace storage {
 
@@ -25,14 +15,7 @@ namespace storage {
 // need a created_at value at save time.
 std::string now_iso8601_utc();
 
-// ── Global settings store (settings.db, key/value) ──────────────────────────
-//
-// Replaces the old config.json file (ADR-0009 rewrite). Lives at
-// <app_data_dir>\settings.db in WAL mode. A generic string KV table; the caller
-// (settings_config.cpp) owns the schema meaning of keys - this layer stays
-// JSON-agnostic. The UI process reads/writes the same table for the settings popup;
-// writes are user-driven and infrequent, so single-writer contention is a
-// non-issue in practice, and WAL keeps reads non-blocking either way.
+// settings.db is a JSON-agnostic key/value store; settings_config owns key meaning.
 
 // Reads all (key,value) rows. Returns true on success (out may be empty when the
 // DB is new/absent - treated as "no saved settings yet", not an error).
@@ -74,10 +57,7 @@ struct ReconcileStats {
 // A per-folder clip database. Open with ClipDb::open(); never construct directly.
 class ClipDb {
 public:
-    // Opens (creating if absent) the DB for a self-contained output folder.
-    //   source "replay" -> <folder>\clips.db ; source "manual" -> <folder>\recs.db
-    // Returns nullptr (and sets *error) if the folder is empty, or if a file is
-    // present but is NOT a valid Monolith clip DB - it is never overwritten.
+    // Return failure for an invalid existing catalog rather than overwriting it.
     static std::unique_ptr<ClipDb> open(const std::wstring& folder,
                                         const std::string& source,
                                         std::string* error);
@@ -105,11 +85,7 @@ class ClipDb {
     // the engine to locate the file for clip_trim.
     std::wstring video_file_for(int64_t id) const;
 
-    // ── Bookmarks (manual recordings only) ────────────────────────────────────
-    // Model borrowed from Vice: one bookmark per clip, identified by a 1-based
-    // `seq`, with a wall-clock offset into the file, an editable label and an
-    // optional #rrggbb color. Written by the engine at recording stop, edited
-    // by the UI afterwards.
+    // Bookmark seq is 1-based per clip; time is a seconds offset into the recording.
     struct BookmarkRow {
         int         seq = 0;
         double      time_seconds = 0.0;
@@ -138,24 +114,14 @@ class ClipDb {
     bool add_hashtag(int64_t id, const std::string& tag, std::string* error);
     bool remove_hashtag(int64_t id, const std::string& tag, std::string* error);
 
-    // Regenerates the first-frame thumbnail for a single clip (used when the UI
-    // finds a thumbnail missing or corrupt). Decodes the video and rewrites the
-    // .png, updating the stored thumbnail_file. Returns false + *error if the
-    // clip/video is missing or decoding fails. Blocking; call off the UI thread.
+    // Blocking decode/thumbnail I/O; call off the UI thread.
     bool regenerate_thumbnail(int64_t id, std::string* error);
 
-    // Renames the clip FILE on disk: moves the video file and its thumbnail to
-    // <new_stem> + original extension (in place, same folder/.thumbs) and updates
-    // the row. new_stem is a base name with no path/extension; invalid or
-    // colliding names fail without touching disk. This is a distinct, optional
-    // action from set_title - the on-screen name is the title, not the filename.
-    // Returns false + *error on any failure.
+    // new_stem has no path or extension; media and thumbnail retain their extensions.
+    // File rename is separate from the display title.
     bool rename_clip(int64_t id, const std::wstring& new_stem, std::string* error);
 
-    // Self-heal + migration. Safe to call from a background thread:
-    //   - row whose video file is gone      -> delete row (+ its thumb)
-    //   - row whose thumbnail is gone/empty  -> regenerate from the video
-    //   - video file on disk with no row     -> import it (+ generate thumb)
+    // Reconcile absent media, missing thumbnails and uncataloged files on a background worker.
     ReconcileStats reconcile(std::string* error);
 
 private:
diff --git a/plugins/stream-deck/src/actions/recording-toggle.ts b/plugins/stream-deck/src/actions/recording-toggle.ts
index 59ee32f..2fe89e8 100644
--- a/plugins/stream-deck/src/actions/recording-toggle.ts
+++ b/plugins/stream-deck/src/actions/recording-toggle.ts
@@ -18,7 +18,7 @@ export class RecordingToggle extends SingletonAction {
             }
             const method = status.recording ? 'recording_stop' : 'recording_start';
             await ipc.request(method);
-            // Optimistic update; status polling corrects it within 5s.
+            // Optimistic state is refreshed by the next status poll.
             await ev.action.setTitle(status.recording ? '⏺ REC' : '⏹ STOP');
             await ev.action.showOk();
         } catch {
diff --git a/plugins/stream-deck/src/plugin.ts b/plugins/stream-deck/src/plugin.ts
index d02b4c4..0e22266 100644
--- a/plugins/stream-deck/src/plugin.ts
+++ b/plugins/stream-deck/src/plugin.ts
@@ -14,8 +14,7 @@ streamDeck.actions.registerAction(new SaveReplay());
 streamDeck.actions.registerAction(new RecordingToggle());
 streamDeck.actions.registerAction(new PauseResume());
 
-// Poll recording state every 5s and push title updates to all active action
-// instances so the key labels stay in sync even without user interaction.
+// Poll status for active action labels.
 setInterval(async () => {
     const status = await ipc.getStatus();
     if (status === null) return;
diff --git a/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/actions/recording-toggle.js b/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/actions/recording-toggle.js
index d907cfe..0a596f0 100644
--- a/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/actions/recording-toggle.js
+++ b/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/actions/recording-toggle.js
@@ -63,7 +63,7 @@ let RecordingToggle = (() => {
                 }
                 const method = status.recording ? 'recording_stop' : 'recording_start';
                 await ipc.request(method);
-                // Optimistic update; status polling corrects it within 5s.
+                // Optimistic state is refreshed by the next status poll.
                 await ev.action.setTitle(status.recording ? '⏺ REC' : '⏹ STOP');
                 await ev.action.showOk();
             }
diff --git a/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/plugin.js b/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/plugin.js
index 8f8e56d..e0bcea8 100644
--- a/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/plugin.js
+++ b/plugins/stream-deck/top.fraa2a.monolith.sdPlugin/bin/plugin.js
@@ -10,8 +10,7 @@ ipc.connect();
 streamDeck.actions.registerAction(new SaveReplay());
 streamDeck.actions.registerAction(new RecordingToggle());
 streamDeck.actions.registerAction(new PauseResume());
-// Poll recording state every 5s and push title updates to all active action
-// instances so the key labels stay in sync even without user interaction.
+// Poll status for active action labels.
 setInterval(async () => {
     const status = await ipc.getStatus();
     if (status === null)