feat: add note surface type with cmux note CLI

CLI/CMUXCLI+CommandSuggestions.swift

@@ -137,6 +137,7 @@ extension CMUXCLI {
         "new-window",
         "new-workspace",
         "next-window",
+        "note",
         "notify",
         "omc",
         "omo",

CLI/CMUXCLI+HermesAgentHooks.swift

@@ -1,5 +1,5 @@
-import Foundation
 import CMUXAgentLaunch
+import Foundation
 
 extension CMUXCLI {
     func hermesAgentShellCommand(_ script: String) -> String {

CLI/CMUXCLI+ThemeSupport.swift

@@ -431,20 +431,12 @@ extension CMUXCLI {
     }
 
     func isRightSidebarCLIMode(_ value: String) -> Bool {
-        switch value.lowercased() {
-        case "files", "find", "vault", "sessions", "feed", "dock":
-            return true
-        default:
-            return false
-        }
+        let normalized = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return Self.availableRightSidebarModeTokens().contains(normalized)
     }
 
     func normalizedRightSidebarCLIArgument(_ value: String) -> String {
-        switch value.lowercased() {
-        case "files", "find", "vault", "sessions", "feed", "dock":
-            return value.lowercased()
-        default:
-            return value
-        }
+        let normalized = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return isRightSidebarCLIMode(normalized) ? normalized : value
     }
 }

CLI/cmux+MarkdownCommand.swift

@@ -0,0 +1,111 @@
+import Foundation
+
+extension CMUXCLI {
+    func runMarkdownCommand(
+        commandArgs: [String],
+        client: SocketClient,
+        jsonOutput: Bool,
+        idFormat: CLIIDFormat
+    ) throws {
+        var args = commandArgs
+
+        // Parse routing flags
+        let (workspaceOpt, argsAfterWorkspace) = parseOption(args, name: "--workspace")
+        let (windowOpt, argsAfterWindow) = parseOption(argsAfterWorkspace, name: "--window")
+        let (surfaceOpt, argsAfterSurface) = parseOption(argsAfterWindow, name: "--surface")
+        let (directionOpt, argsAfterDirection) = parseOption(argsAfterSurface, name: "--direction")
+        let (focusOpt, argsAfterFocus) = parseOption(argsAfterDirection, name: "--focus")
+        let (fontSizeOpt, argsAfterFontSize) = parseOption(argsAfterFocus, name: "--font-size")
+        args = argsAfterFontSize
+
+        let fontSize = try fontSizeOpt.map(parseMarkdownViewerFontSize)
+
+        // Determine subcommand. Explicit "open" is supported, otherwise treat
+        // a single positional argument as shorthand path.
+        let subArgs: [String]
+        if let first = args.first, first.lowercased() == "open" {
+            subArgs = Array(args.dropFirst())
+        } else if args.count == 1, let first = args.first, !first.hasPrefix("-") {
+            subArgs = [first]
+        } else {
+            // Allow path-like first tokens (e.g. plan.md) with trailing args
+            // so we can surface specific trailing-arg/flag errors below.
+            if let first = args.first, first.hasPrefix("-") {
+                throw CLIError(
+                    message:
+                        "markdown open: unknown flag '\(first)'. Usage: cmux markdown open <path> [--workspace <id|ref|index>] [--surface <id|ref|index>] [--window <id|ref|index>] [--direction right|down|left|up] [--focus <true|false>] [--font-size <points>]"
+                )
+            } else if let first = args.first, looksLikePath(first) || first.contains(".") {
+                subArgs = args
+            } else if let first = args.first {
+                throw CLIError(message: "Unknown markdown subcommand: \(first). Usage: cmux markdown open <path>")
+            } else {
+                subArgs = []
+            }
+        }
+
+        guard let rawPath = subArgs.first, !rawPath.isEmpty else {
+            throw CLIError(message: "markdown open requires a file path. Usage: cmux markdown open <path>")
+        }
+        let trailingArgs = Array(subArgs.dropFirst())
+        if let unknownFlag = trailingArgs.first(where: { $0.hasPrefix("-") }) {
+            throw CLIError(
+                message:
+                    "markdown open: unknown flag '\(unknownFlag)'. Usage: cmux markdown open <path> [--workspace <id|ref|index>] [--surface <id|ref|index>] [--window <id|ref|index>] [--direction right|down|left|up] [--focus <true|false>] [--font-size <points>]"
+            )
+        }
+        if let extraArg = trailingArgs.first {
+            throw CLIError(
+                message:
+                    "markdown open: unexpected argument '\(extraArg)'. Usage: cmux markdown open <path> [--workspace <id|ref|index>] [--surface <id|ref|index>] [--window <id|ref|index>] [--direction right|down|left|up] [--focus <true|false>] [--font-size <points>]"
+            )
+        }
+
+        let absolutePath = resolvePath(rawPath)
+
+        // Build params
+        let direction = directionOpt ?? "right"
+        var params: [String: Any] = ["path": absolutePath, "direction": direction]
+        if let fontSize {
+            params["font_size"] = fontSize
+        }
+        if let surfaceRaw = surfaceOpt {
+            if let surface = try normalizeSurfaceHandle(surfaceRaw, client: client) {
+                params["surface_id"] = surface
+            }
+        }
+        let workspaceRaw = workspaceOpt ?? (windowOpt == nil ? ProcessInfo.processInfo.environment["CMUX_WORKSPACE_ID"] : nil)
+        if let workspaceRaw {
+            if let workspace = try normalizeWorkspaceHandle(workspaceRaw, client: client) {
+                params["workspace_id"] = workspace
+            }
+        }
+        if let windowRaw = windowOpt {
+            if let window = try normalizeWindowHandle(windowRaw, client: client) {
+                params["window_id"] = window
+            }
+        }
+        try applyFocusOption(focusOpt, defaultValue: false, to: &params)
+
+        let payload = try client.sendV2(method: "markdown.open", params: params)
+
+        if jsonOutput {
+            print(jsonString(formatIDs(payload, mode: idFormat)))
+        } else {
+            let surfaceText = formatHandle(payload, kind: "surface", idFormat: idFormat) ?? "unknown"
+            let paneText = formatHandle(payload, kind: "pane", idFormat: idFormat) ?? "unknown"
+            let filePath = (payload["path"] as? String) ?? absolutePath
+            print("OK surface=\(surfaceText) pane=\(paneText) path=\(filePath)")
+        }
+    }
+
+    // MARK: - Note Commands
+
+    /// Subcommand dispatcher for `cmux note <verb>`. Verbs:
+    ///   new   — create (if missing), optionally attach, and open a project note
+    ///   open  — open an existing slug (error if missing)
+    ///   list  — list all notes in the project
+    ///   path  — print the absolute path for a slug
+    ///   read  — print note content
+    ///   write — replace note content
+}

CLI/cmux+RightSidebarAvailability.swift

@@ -0,0 +1,119 @@
+import Foundation
+
+extension CMUXCLI {
+    private static func appDefaultsCandidates(environment: [String: String] = ProcessInfo.processInfo.environment) -> [UserDefaults] {
+        var candidates: [UserDefaults] = []
+        if let bundleId = normalizedEnvValue(environment["CMUX_BUNDLE_ID"]),
+           let defaults = UserDefaults(suiteName: bundleId) {
+            candidates.append(defaults)
+        }
+        if let bundleId = containingAppBundleIdentifier(),
+           let defaults = UserDefaults(suiteName: bundleId) {
+            candidates.append(defaults)
+        }
+        // A CLI launched from PATH or automation has no CMUX_BUNDLE_ID and is
+        // not inside the .app bundle; without the release app's suite it would
+        // fall through to the CLI's own empty `.standard` domain and report
+        // app-enabled beta modes as unavailable (mirrors browserSettingsDomain).
+        if let defaults = UserDefaults(suiteName: defaultBrowserSettingsDomain) {
+            candidates.append(defaults)
+        }
+        candidates.append(.standard)
+        return candidates
+    }
+
+    private static func betaFeatureEnabled(
+        key: String,
+        defaultValue: Bool = false,
+        environment: [String: String] = ProcessInfo.processInfo.environment
+    ) -> Bool {
+        for defaults in appDefaultsCandidates(environment: environment) {
+            if defaults.object(forKey: key) != nil {
+                return defaults.bool(forKey: key)
+            }
+        }
+        return defaultValue
+    }
+
+    static func availableRightSidebarModeTokens(
+        environment: [String: String] = ProcessInfo.processInfo.environment
+    ) -> [String] {
+        var tokens = ["files", "find", "vault", "sessions"]
+        if betaFeatureEnabled(key: rightSidebarNotesEnabledDefaultsKey, environment: environment) {
+            tokens.append("notes")
+        }
+        if betaFeatureEnabled(key: rightSidebarFeedEnabledDefaultsKey, environment: environment) {
+            tokens.append("feed")
+        }
+        if betaFeatureEnabled(key: rightSidebarDockEnabledDefaultsKey, environment: environment) {
+            tokens.append("dock")
+        }
+        return tokens
+    }
+
+    static func rightSidebarUsage(environment: [String: String] = ProcessInfo.processInfo.environment) -> String {
+        let modes = availableRightSidebarModeTokens(environment: environment).joined(separator: "|")
+        let template = String(localized: "cli.rightSidebar.usage.template", defaultValue: """
+            Usage: cmux right-sidebar <command> [flags]
+
+            Control the right sidebar from the CLI.
+
+            Commands:
+              toggle                         Toggle right sidebar visibility
+              show                           Show the right sidebar
+              hide                           Hide the right sidebar
+              focus                          Focus the current right sidebar mode
+              set <%@>
+                                             Show, switch mode, and focus
+              mode                           Print {"visible":bool,"mode":string}
+              %@
+                                             Alias for show + set + focus
+
+            Flags:
+              --workspace <id|ref|index>     Target the window containing a workspace
+              --window <id|ref|index>        Target a window
+              --no-focus                     With set, switch mode without moving focus
+
+            Examples:
+              cmux right-sidebar toggle
+              cmux right-sidebar set find
+              cmux right-sidebar set vault --no-focus
+              cmux right-sidebar mode
+        """)
+        return String(format: template, modes, modes)
+    }
+
+    static func noteGlobalUsage(environment: [String: String] = ProcessInfo.processInfo.environment) -> String {
+        guard betaFeatureEnabled(key: rightSidebarNotesEnabledDefaultsKey, environment: environment) else {
+            return ""
+        }
+        let usage = String(localized: "cli.note.globalUsage", defaultValue: """
+          note new [--slug <name>] [--attach <none|workspace|surface|terminal>] [--title <text>] [--direction <dir>] [--focus <true|false>]
+          note open <slug> [--attach <none|workspace|surface|terminal>] [--direction <dir>] [--focus <true|false>]
+          note list [--json]                                                     (list notes in the project)
+          note here [--json]                                                     (print the note resolved for the calling surface)
+          note path <slug>                                                       (print absolute path for a note slug)
+          note read <slug>                                                       (print note content)
+          note write <slug> [--text <text>|--stdin|<text...>] [--create <true|false>]
+          note append <slug> [--text <text>|--stdin|<text...>] [--create <true|false>]
+          note rm <slug>                                                         (delete a note file)
+          """)
+        return "\n\(usage)\n"
+    }
+
+    // Presentation flags are global, but command option values can also look like flags.
+    static let commandOptionsWithValues: Set<String> = [
+        "--action", "--after-workspace", "--agent", "--amount", "--arch",
+        "--attr", "--before-workspace", "--body", "--color", "--command",
+        "--config", "--create", "--cwd", "--description", "--direction", "--domain",
+        "--dx", "--dy", "--email", "--event", "--expires", "--focus",
+        "--function", "--id", "--image", "--index", "--key", "--kind",
+        "--label", "--layout", "--lines", "--load-state", "--max-depth", "--name", "--os",
+        "--order", "--out", "--pane", "--panel", "--path", "--profile", "--property",
+        "--provider", "--relay-port", "--script", "--selector", "--session",
+        "--shell", "--source", "--subtitle", "--surface", "--tab", "--target-pane", "--team",
+        "--text", "--timeout", "--timeout-ms", "--title", "--transcript",
+        "--turn", "--type", "--url", "--url-contains", "--value", "--window",
+        "--workspace", "--checkpoint", "--checkpoint-id",
+    ]
+}