Align Gateway settings pane with embed controller contract

Rename the local Gateway controller to GatewayEmbedController with a
shared singleton for Settings and the menu bar. Decode pairing payload
as object or string, reject loopback QR URLs, open ~/.config/vocagateway
for logs, and surface Pair phone from the tray when Pairable.

Author: jatinkrmalik

Sources/VocaMac/App/VocaMacApp.swift

@@ -12,11 +12,18 @@ final class SettingsWindowManager: ObservableObject {
     private var settingsWindow: NSWindow?
     private var closeObserver: NSObjectProtocol?
 
-    func open(appState: AppState) {
+    func open(appState: AppState, page: SettingsPage? = nil) {
         // If window already exists, just bring it to front
         if let window = settingsWindow, window.isVisible {
             window.makeKeyAndOrderFront(nil)
             NSApp.activate(ignoringOtherApps: true)
+            if let page {
+                NotificationCenter.default.post(
+                    name: .selectSettingsPage,
+                    object: nil,
+                    userInfo: ["page": page.rawValue]
+                )
+            }
             return
         }
 
@@ -43,6 +50,14 @@ final class SettingsWindowManager: ObservableObject {
         DockVisibilityCoordinator.shared.windowDidOpen()
         NSApp.activate(ignoringOtherApps: true)
 
+        if let page {
+            NotificationCenter.default.post(
+                name: .selectSettingsPage,
+                object: nil,
+                userInfo: ["page": page.rawValue]
+            )
+        }
+
         // Held so it can be removed on close — a block-based observer lives
         // until its token is released, so opening repeatedly would otherwise
         // stack up observers.

…Mac/Services/GatewayProcessManager.swift …ac/Services/GatewayEmbedController.swiftSources/VocaMac/Services/GatewayProcessManager.swift renamed to Sources/VocaMac/Services/GatewayEmbedController.swift Sources/VocaMac/Services/GatewayProcessManager.swift renamed to Sources/VocaMac/Services/GatewayEmbedController.swift

@@ -1,4 +1,4 @@
-// GatewayProcessManager.swift
+// GatewayEmbedController.swift
 // VocaMac
 //
 // Native-first start/stop and health/pairing probes for a local VocaGateway.
@@ -15,6 +15,9 @@ enum GatewayPaths {
     static let docsURL = URL(string: "https://vocagateway.vocahq.com/")!
     static let githubURL = URL(string: "https://github.com/VocaHQ/vocagateway")!
     static let dockerDesktopURL = URL(string: "https://www.docker.com/products/docker-desktop/")!
+    static let dockerInstallURL = URL(string: "https://docs.docker.com/desktop/setup/install/mac-install/")!
+    static let vocagatewayREADME = URL(string: "https://github.com/VocaHQ/vocagateway#readme")!
+    static let publicURLOverrideDefaultsKey = "vocamac.gateway.publicURLOverride"
 
     static var configDirectory: URL {
         FileManager.default.homeDirectoryForCurrentUser
@@ -57,6 +60,9 @@ enum GatewayBinaryResolver {
         fileManager: FileManager = .default,
         pathEnvironment: String? = ProcessInfo.processInfo.environment["PATH"]
     ) -> String? {
+        if let fromWhich = whichViaBin(named: "vocagateway", fileManager: fileManager) {
+            return fromWhich
+        }
         if let fromPath = findOnPATH(
             named: "vocagateway",
             pathEnvironment: pathEnvironment,
@@ -72,6 +78,27 @@ enum GatewayBinaryResolver {
         return nil
     }
 
+    static func whichViaBin(named name: String, fileManager: FileManager) -> String? {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/which")
+        process.arguments = [name]
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = Pipe()
+        do {
+            try process.run()
+            process.waitUntilExit()
+        } catch {
+            return nil
+        }
+        guard process.terminationStatus == 0 else { return nil }
+        let data = pipe.fileHandleForReading.readDataToEndOfFile()
+        let path = String(data: data, encoding: .utf8)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !path.isEmpty, fileManager.isExecutableFile(atPath: path) else { return nil }
+        return path
+    }
+
     static func findOnPATH(
         named name: String,
         pathEnvironment: String?,
@@ -102,38 +129,43 @@ enum GatewayBinaryResolver {
 }
 
 
-/// UI / runtime state for the embedded Gateway control.
-enum GatewayRuntimeStatus: Equatable {
-    case stopped
-    case starting
-    case pairable
-    case ready
-    case error(String)
-
-    var title: String {
-        switch self {
-        case .stopped: return "Stopped"
-        case .starting: return "Starting…"
-        case .pairable: return "Pairable"
-        case .ready: return "Ready"
-        case .error: return "Error"
+
+@MainActor
+final class GatewayEmbedController: ObservableObject {
+    static let shared = GatewayEmbedController()
+
+    enum Status: Equatable {
+        case stopped
+        case starting
+        case pairable
+        case ready
+        case error(String)
+
+        var title: String {
+            switch self {
+            case .stopped: return "Stopped"
+            case .starting: return "Starting"
+            case .pairable: return "Pairable"
+            case .ready: return "Ready"
+            case .error: return "Error"
+            }
+        }
+
+        var detail: String? {
+            if case .error(let message) = self { return message }
+            return nil
         }
-    }
 
-    /// True when Settings/tray may offer Pair phone (non-loopback QR ready).
-    var allowsPairing: Bool {
-        switch self {
-        case .pairable, .ready: return true
-        default: return false
+        var allowsPairing: Bool {
+            switch self {
+            case .pairable, .ready: return true
+            default: return false
+            }
         }
     }
-}
 
-@MainActor
-final class GatewayProcessManager: ObservableObject {
-    static let shared = GatewayProcessManager()
 
-    @Published private(set) var status: GatewayRuntimeStatus = .stopped
+    @Published private(set) var status: Status = .stopped
     @Published private(set) var binaryPath: String?
     @Published private(set) var isBinaryAvailable = false
     @Published private(set) var isDockerAvailable = false
@@ -143,14 +175,19 @@ final class GatewayProcessManager: ObservableObject {
     @Published private(set) var lastErrorMessage: String?
     @Published private(set) var isLive = false
     @Published private(set) var isReady = false
-    @Published var publicURLOverride: String = ""
+    @Published var publicURLOverride: String {
+        didSet {
+            UserDefaults.standard.set(publicURLOverride, forKey: GatewayPaths.publicURLOverrideDefaultsKey)
+        }
+    }
 
     private var process: Process?
     private var stdoutPipe: Pipe?
     private let session: URLSession
 
     init(session: URLSession = .shared) {
         self.session = session
+        self.publicURLOverride = UserDefaults.standard.string(forKey: GatewayPaths.publicURLOverrideDefaultsKey) ?? ""
         refreshBinaryAvailability()
     }
 
@@ -167,7 +204,7 @@ final class GatewayProcessManager: ObservableObject {
     func start() async {
         refreshBinaryAvailability()
         guard let binaryPath else {
-            let message = "VocaGateway is not installed. Install the native CLI, or use Docker as a fallback."
+            let message = "VocaGateway is not installed. Install the native CLI, or use Docker as a fallback (no MLX / Apple Silicon native engines)."
             status = .error(message)
             lastErrorMessage = message
             return
@@ -231,7 +268,7 @@ final class GatewayProcessManager: ObservableObject {
     func refreshStatus() async {
         refreshBinaryAvailability()
 
-        let live = await probe(path: "/health/live")
+        let live = await probe(path: "/")
         let ready = await probe(path: "/health/ready")
         isLive = live
         isReady = ready
@@ -316,7 +353,7 @@ final class GatewayProcessManager: ObservableObject {
             }
             pairingPayloadRaw = json["payload"] as? String
 
-            switch GatewayPairingCodec.decodeAdminResponse(json, rejectLoopback: true) {
+            switch GatewayPairingDecoder.decodeAdminJSON(json, rejectLoopback: true) {
             case .success(let payload):
                 pairingPayload = payload
                 status = isReady ? .ready : .pairable
@@ -345,7 +382,12 @@ final class GatewayProcessManager: ObservableObject {
     }
 
     func openDockerDesktopInstall() {
-        NSWorkspace.shared.open(GatewayPaths.dockerDesktopURL)
+        NSWorkspace.shared.open(GatewayPaths.dockerInstallURL)
+    }
+
+    func openDockerFallbackDocs() {
+        NSWorkspace.shared.open(GatewayPaths.dockerInstallURL)
+        NSWorkspace.shared.open(GatewayPaths.vocagatewayREADME)
     }
 
     func openGatewayRepo() {
@@ -354,27 +396,23 @@ final class GatewayProcessManager: ObservableObject {
 
     /// Reveal Gateway's documented log path (not VocaMac Application Support).
     func openGatewayLogs() {
-        let logFile = GatewayPaths.macOSLogFileURL
-        let logDir = GatewayPaths.macOSLogDirectory
-        let fm = FileManager.default
-        if fm.fileExists(atPath: logFile.path) {
-            NSWorkspace.shared.selectFile(logFile.path, inFileViewerRootedAtPath: logDir.path)
-            return
-        }
-        if fm.fileExists(atPath: logDir.path) {
-            NSWorkspace.shared.open(logDir)
-            return
-        }
         let configDir = GatewayPaths.configDirectory
+        let fm = FileManager.default
         if fm.fileExists(atPath: configDir.path) {
             NSWorkspace.shared.open(configDir)
             return
         }
-        lastErrorMessage = "No Gateway log file yet. LaunchAgent installs write to ~/Library/Logs/VocaGateway/. Session starts from VocaMac tee process stdout only."
+        let parent = configDir.deletingLastPathComponent()
+        if fm.fileExists(atPath: parent.path) {
+            NSWorkspace.shared.open(parent)
+            return
+        }
+        lastErrorMessage = "Gateway config folder ~/.config/vocagateway does not exist yet. It appears after the first native Gateway start."
     }
 
+
     func copyPairingURLToPasteboard() {
-        guard let url = pairingPayload?.url.absoluteString else { return }
+        guard let url = pairingPayload?.url else { return }
         let pasteboard = NSPasteboard.general
         pasteboard.clearContents()
         pasteboard.setString(url, forType: .string)
@@ -437,7 +475,7 @@ final class GatewayProcessManager: ObservableObject {
         }
 #else
         throw NSError(
-            domain: "GatewayProcessManager",
+            domain: "GatewayEmbedController",
             code: 1,
             userInfo: [NSLocalizedDescriptionKey: "Native Gateway process control is only available on macOS."]
         )

Sources/VocaMac/Views/GatewaySettingsTab.swift

@@ -17,14 +17,14 @@ extension Notification.Name {
 }
 
 struct GatewaySettingsTab: View {
-    @ObservedObject private var gateway = GatewayProcessManager.shared
+    @ObservedObject private var gateway = GatewayEmbedController.shared
     @State private var showingPairSheet = false
     @State private var copiedURL = false
 
     var body: some View {
         Form {
             Section {
-                Text("Optional self-hosted compute for phones and other Voca clients. This is not on-device transcription; audio goes to the Gateway host you run.")
+                Text("VocaGateway is an optional companion that exposes local speech APIs to phones and other clients. It is not an on-device VocaMac engine, and it does not replace the speech models you already run here.")
                     .font(.caption)
                     .foregroundStyle(.secondary)
                     .fixedSize(horizontal: false, vertical: true)
@@ -129,7 +129,7 @@ struct GatewaySettingsTab: View {
                         Button {
                             showingPairSheet = true
                         } label: {
-                            Label("Show Pair Phone QR", systemImage: "qrcode")
+                            Label("Pair phone…", systemImage: "qrcode")
                         }
                         .buttonStyle(.borderedProminent)
 
@@ -163,13 +163,13 @@ struct GatewaySettingsTab: View {
 
             if !gateway.isBinaryAvailable {
                 Section("Docker fallback") {
-                    Text("Native start is the happy path. Docker Desktop is only a fallback when vocagateway is missing.")
+                    Text("Native `vocagateway` is the happy path. Docker Compose is a fallback only. Docker images do not include MLX or Apple Silicon native engines.")
                         .font(.caption)
                         .foregroundStyle(.secondary)
 
                     HStack {
                         Button {
-                            gateway.openDockerDesktopInstall()
+                            gateway.openDockerFallbackDocs()
                         } label: {
                             Label(
                                 gateway.isDockerAvailable ? "Docker Desktop docs" : "Install Docker Desktop",
@@ -178,13 +178,13 @@ struct GatewaySettingsTab: View {
                         }
 
                         Button {
-                            gateway.openGatewayDocs()
+                            NSWorkspace.shared.open(GatewayPaths.docsURL)
                         } label: {
                             Label("Gateway install docs", systemImage: "book")
                         }
 
                         Button {
-                            gateway.openGatewayRepo()
+                            NSWorkspace.shared.open(GatewayPaths.githubURL)
                         } label: {
                             Label("GitHub", systemImage: "chevron.left.forwardslash.chevron.right")
                         }
@@ -193,7 +193,7 @@ struct GatewaySettingsTab: View {
             }
 
             Section("Logs") {
-                Text("Gateway owns its logs. VocaMac opens Gateway's path under ~/Library/Logs/VocaGateway or ~/.config/vocagateway — it does not store Gateway logs under VocaMac Application Support.")
+                Text("Gateway owns its logs. VocaMac opens ~/.config/vocagateway (Gateway config and documented log path). It does not write Gateway logs under VocaMac Application Support.")
                     .font(.caption)
                     .foregroundStyle(.secondary)
 
@@ -215,7 +215,7 @@ struct GatewaySettingsTab: View {
         }
         .sheet(isPresented: $showingPairSheet) {
             GatewayPairPhoneSheet(
-                payloadRaw: gateway.pairingPayloadRaw
+                payloadRaw: gateway.pairingPayload?.qrPayloadString
                     ?? gateway.pairingPayload.map { encodeCompactPayload($0) },
                 urlString: gateway.pairingPayload?.url,
                 onCopyURL: {
@@ -249,8 +249,8 @@ struct GatewaySettingsTab: View {
 
     private func encodeCompactPayload(_ payload: GatewayPairingPayload) -> String {
         let object: [String: Any] = [
-            "v": payload.version,
-            "url": payload.url.absoluteString,
+            "v": payload.v,
+            "url": payload.url,
             "token": payload.token,
         ]
         guard let data = try? JSONSerialization.data(withJSONObject: object, options: [.sortedKeys]),

Sources/VocaMac/Views/MenuBarView.swift

@@ -92,7 +92,7 @@ struct MenuBarView: View {
     @EnvironmentObject var appState: AppState
     @ObservedObject var settingsManager: SettingsWindowManager
     @ObservedObject var updateWindowManager: UpdateWindowManager
-    @ObservedObject private var gateway = GatewayProcessManager.shared
+    @ObservedObject private var gateway = GatewayEmbedController.shared
     @StateObject private var processMonitor = ProcessMonitor()
     @State private var audioDevices: [AudioDevice] = []