diff --git a/apps/macos/Sources/Clawdis/ClawdisPaths.swift b/apps/macos/Sources/Clawdis/ClawdisPaths.swift
index 0fdbc8d59..ddac27f70 100644
--- a/apps/macos/Sources/Clawdis/ClawdisPaths.swift
+++ b/apps/macos/Sources/Clawdis/ClawdisPaths.swift
@@ -2,6 +2,7 @@ import Foundation
 
 enum ClawdisEnv {
     static func path(_ key: String) -> String? {
+        // Normalize env overrides once so UI + file IO stay consistent.
         guard let value = ProcessInfo.processInfo.environment[key]?
             .trimmingCharacters(in: .whitespacesAndNewlines),
             !value.isEmpty
diff --git a/apps/macos/Sources/Clawdis/DeviceModelCatalog.swift b/apps/macos/Sources/Clawdis/DeviceModelCatalog.swift
index 02a1bd00f..98ffb011b 100644
--- a/apps/macos/Sources/Clawdis/DeviceModelCatalog.swift
+++ b/apps/macos/Sources/Clawdis/DeviceModelCatalog.swift
@@ -122,6 +122,7 @@ enum DeviceModelCatalog {
     }
 
     private static func locateResourceBundle() -> Bundle? {
+        // Prefer module bundle (SwiftPM/tests), then main app bundle (packaged app).
         if let bundle = self.bundleIfContainsDeviceModels(Bundle.module) {
             return bundle
         }
diff --git a/apps/macos/Sources/Clawdis/SettingsRootView.swift b/apps/macos/Sources/Clawdis/SettingsRootView.swift
index 655bd9644..203ef2202 100644
--- a/apps/macos/Sources/Clawdis/SettingsRootView.swift
+++ b/apps/macos/Sources/Clawdis/SettingsRootView.swift
@@ -105,6 +105,7 @@ struct SettingsRootView: View {
     }
 
     private var nixManagedBanner: some View {
+        // Prefer gateway-resolved paths; fall back to local env defaults if disconnected.
         let snapshotPaths = GatewayConnection.shared.snapshotPaths()
         let configPath = snapshotPaths.configPath ?? ClawdisPaths.configURL.path
         let stateDir = snapshotPaths.stateDir ?? ClawdisPaths.stateDirURL.path
diff --git a/src/gateway/server.ts b/src/gateway/server.ts
index 425481422..2d7a885af 100644
--- a/src/gateway/server.ts
+++ b/src/gateway/server.ts
@@ -639,6 +639,7 @@ function buildSnapshot(): Snapshot {
     health: emptyHealth,
     stateVersion: { presence: presenceVersion, health: healthVersion },
     uptimeMs,
+    // Surface resolved paths so UIs can display the true config location.
     configPath: CONFIG_PATH_CLAWDIS,
     stateDir: STATE_DIR_CLAWDIS,
   };