[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AMTHHE05P7HE646JBWW9WS":3,"skill-same:01M7AMTHHE05P7HE646JBWW9WS":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7AMTHHE05P7HE646JBWW9WS","desktop-macos-platform",null,"Use when building, porting, or debugging a native macOS app. Covers the framework decision and the four architectures of a desktop app (the router for the whole desktop-apps-macos-linux reference), the Darwin stack, bundles, the run loop\u002FGCD\u002Fmain thread, XPC privilege separation, Apple silicon, Rosetta, and universal binaries, the 2026 SwiftUI-vs-AppKit state of play and the interop seam, Liquid Glass (macOS 26 Tahoe), Mac Catalyst, Swift 6 strict concurrency migration, and persistence on macOS (SwiftData, Core Data, GRDB).","the-vibey-project\u002Fvibey","the-vibey-project","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F329298758?v=4","01M7AJHGZ9722CTJ4JNQZVRH0Q","the vibey project","01M7AJHGZVMG2K7TGXQ6XFHVG3",5,"MIT","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdesktop-apps-macos-linux\u002Fskills\u002Fdesktop-macos-platform\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: desktop-macos-platform\ndescription: \"Use when building, porting, or debugging a native macOS app. Covers the framework decision and the four architectures of a desktop app (the router for the whole desktop-apps-macos-linux reference), the Darwin stack, bundles, the run loop\u002FGCD\u002Fmain thread, XPC privilege separation, Apple silicon, Rosetta, and universal binaries, the 2026 SwiftUI-vs-AppKit state of play and the interop seam, Liquid Glass (macOS 26 Tahoe), Mac Catalyst, Swift 6 strict concurrency migration, and persistence on macOS (SwiftData, Core Data, GRDB).\"\n---\n\n# Desktop Apps (macOS & Linux): macOS Platform, SwiftUI\u002FAppKit, and Swift\n\n> **Part 1 of 5** of the *Desktop Application Programming — macOS & Linux* reference (plugin `desktop-apps-macos-linux`), covering §0–§3. Sibling skills: `desktop-linux-platform` (§4–§6), `desktop-cross-platform-and-architecture` (§7–§9), `desktop-packaging-security-and-testing` (§10–§13), `desktop-reference` (§14–§20). Section numbers are shared across the set; a reference written as §N → `skill` points into that sibling skill.\n>\n> **Currency:** Verified August 2026. See §18 → `desktop-reference` for the currency snapshot and what goes stale first.\n\n> **How to read this.** Reference, not tutorial. Sections are independent. Three markers:\n> - **[UNIVERSAL]** — true of desktop software regardless of platform or toolkit.\n> - **[PLATFORM]** — specific to macOS or a particular Linux stack. Verify against current docs.\n> - **[CONTESTED]** — competent engineers disagree. Both cases given; don't adjudicate for the reader.\n>\n> **⚠️ GOTCHA** boxes mark the failure modes that actually cost people days.\n>\n> **The single most important framing in this document:** macOS is *one* platform with\n> *one* vendor, *one* HIG, and *one* blessed path. Linux is *not a platform* — it is a\n> family of overlapping conventions (freedesktop specs), two dominant toolkits, two\n> display protocols, three packaging formats, and a dozen desktop environments. Advice\n> that treats them symmetrically is wrong. Almost every difficulty in cross-platform\n> desktop work traces back to this asymmetry.\n\n---\n\n## §0. Routing — Classify Before Answering\n\n### 0.1 The framework decision, up front\n\n| If the answer to this is yes... | ...then |\n|---|---|\n| macOS-only, deep OS integration, sold on the Mac App Store | **SwiftUI + AppKit** |\n| macOS + iOS from one codebase | **SwiftUI** (multiplatform target, not Catalyst) |\n| Linux-first, GNOME-native feel, will ship on Flathub | **GTK4 + libadwaita** |\n| Linux-first, KDE-native, or Linux+Windows+macOS with one native-ish toolkit | **Qt 6** |\n| Team is web developers; you already have a web app; deadline dominates | **Electron** |\n| Team can take on Rust; bundle size \u002F memory matter; want a small attack surface | **Tauri 2** |\n| Existing .NET\u002FWPF codebase and skills; need Linux | **Avalonia** |\n| Existing Kotlin\u002FAndroid codebase; JVM shop | **Compose Multiplatform** |\n| Pixel-identical custom UI on every OS, mobile too, don't care about native feel | **Flutter** |\n| It's a developer tool \u002F internal utility; native feel is irrelevant | Anything. Ship it. |\n\n**[UNIVERSAL] The framework decision is downstream of two questions people skip:**\n1. **Who maintains this in three years?** Framework choice is a hiring and staffing\n   decision more than a technical one. A \"better\" framework nobody on the team knows is\n   worse.\n2. **Does this app need to feel native, or merely to work?** These have completely\n   different cost curves. \"Feels native\" means platform menus, platform keyboard\n   conventions, platform file dialogs, platform accessibility, platform theming,\n   platform window behaviour — and it is 3–10× the work of \"works.\"\n\n### 0.2 The four architectures of a desktop app\n\n```\nA. Pure native, per platform     — two codebases, best feel, highest cost\nB. Native UI + shared core       — Rust\u002FC++\u002FGo core, SwiftUI on Mac, GTK\u002FQt on Linux\n                                   (the \"right\" answer for serious cross-platform apps)\nC. Single cross-platform toolkit — Qt \u002F Flutter \u002F Avalonia \u002F Compose. One UI, everywhere.\nD. Web UI in a shell            — Electron \u002F Tauri. One UI, everywhere, web tech.\n```\n**B is underrated.** Ghostty (Zig core + SwiftUI on macOS + GTK4 on Linux), 1Password\n(Rust core), Signal, and many others use it. The core is testable, portable, and\nperformance-critical; the UI is thin and idiomatic per platform. The cost is that you\nwrite the UI twice — but the UI is usually the *smaller* half of a serious application,\nand it's the half where \"twice\" buys you the most.\n\n### 0.3 The question-type router\n\n| Asked about... | Go to |\n|---|---|\n| Bundles, launchd, run loops, Darwin, XPC | §1 |\n| SwiftUI, AppKit, NSViewRepresentable, Liquid Glass, menus, windows | §2 |\n| Swift concurrency, @MainActor, SwiftData\u002FCore Data | §3 |\n| D-Bus, systemd user units, XDG specs, PipeWire, desktop files | §4 → `desktop-linux-platform` |\n| GTK4, libadwaita, Qt6, QML, toolkit choice on Linux | §5 → `desktop-linux-platform` |\n| Wayland, X11, XWayland, compositors, protocols | §6 → `desktop-linux-platform` |\n| Electron, Tauri, Flutter, Avalonia, Compose, Rust GUI | §7 → `desktop-cross-platform-and-architecture` |\n| MVVM, state management, undo, documents, IPC, threading | §8 → `desktop-cross-platform-and-architecture` |\n| Windows, keyboard, drag & drop, HiDPI, dark mode, i18n, a11y | §9 → `desktop-cross-platform-and-architecture` |\n| Notarization, DMG, Flatpak, Snap, AppImage, .deb\u002F.rpm, AppStream | §10 → `desktop-packaging-security-and-testing` |\n| Sparkle, auto-update, delta updates, rollout | §11 → `desktop-packaging-security-and-testing` |\n| TCC, entitlements, hardened runtime, portals, Electron security | §12 → `desktop-packaging-security-and-testing` |\n| UI testing, profiling, Instruments, sysprof, CI | §13 → `desktop-packaging-security-and-testing` |\n| \"Don't do this\" | §14 → `desktop-reference` |\n| \"Which is better, X or Y?\" | §15 → `desktop-reference` (contested) |\n| Books, docs, HIGs, authorities | §16 → `desktop-reference` |\n| Famous failures and lessons | §17 → `desktop-reference` |\n| \"Is this still current?\" | §18 → `desktop-reference` |\n\n---\n\n## §1. macOS Platform Architecture\n\n### 1.1 The stack\n\n```\n┌──────────────────────────────────────────────────┐\n│ Your app: SwiftUI \u002F AppKit \u002F Catalyst \u002F 3rd-party│\n├──────────────────────────────────────────────────┤\n│ App frameworks: AppKit, SwiftUI, UIKit(Catalyst) │\n├──────────────────────────────────────────────────┤\n│ Media\u002Fgraphics: Core Animation, Metal, Core Image,│\n│ AVFoundation, Core Text                          │\n├──────────────────────────────────────────────────┤\n│ Core Services: Foundation, Core Foundation, GCD, │\n│ Core Data, Network.framework, XPC                │\n├──────────────────────────────────────────────────┤\n│ Darwin: XNU kernel (Mach + BSD), launchd, dyld,  │\n│ APFS, Sandbox (Seatbelt), TCC, AMFI, SIP         │\n└──────────────────────────────────────────────────┘\n```\n\n**Things that matter and are non-obvious:**\n- **XNU is a hybrid kernel**: Mach (ports, IPC, VM, scheduling) + BSD (POSIX, sockets,\n  VFS). Mach ports are the substrate for XPC and for essentially all privileged IPC.\n- **launchd is PID 1** and the *only* supported way to run background processes. Not\n  cron, not init scripts, not a daemon you fork yourself.\n  - `LaunchAgents` run per-user in the GUI session (`~\u002FLibrary\u002FLaunchAgents`,\n    `\u002FLibrary\u002FLaunchAgents`). `LaunchDaemons` run as root, system-wide, with no GUI\n    session (`\u002FLibrary\u002FLaunchDaemons`).\n  - Modern apps should prefer **`SMAppService`** (macOS 13+) to register login items and\n    helpers from *inside* the app bundle, rather than dropping plists into\n    `~\u002FLibrary\u002FLaunchAgents`. The user then manages them in System Settings → General →\n    Login Items, which is what they expect.\n- **dyld** is the dynamic linker; the **dyld shared cache** is why system frameworks load\n  fast. `DYLD_*` environment variables are ignored for hardened-runtime and\n  SIP-protected processes — which is exactly why your `DYLD_LIBRARY_PATH` trick works in\n  development and fails in the notarized build.\n- **SIP (System Integrity Protection)** makes `\u002FSystem`, `\u002Fusr` (except `\u002Fusr\u002Flocal`),\n  and `\u002Fbin` immutable even to root. Never write outside `\u002Fusr\u002Flocal`, `\u002Fopt`, or the\n  app's own container.\n\n### 1.2 Bundles — the unit of macOS software\n\n```\nMyApp.app\u002F\n└── Contents\u002F\n    ├── Info.plist              ← identity, version, doc types, URL schemes, usage strings\n    ├── MacOS\u002F\n    │   └── MyApp               ← the actual executable (CFBundleExecutable)\n    ├── Resources\u002F\n    │   ├── Assets.car          ← compiled asset catalog (icons, images, colors)\n    │   ├── en.lproj\u002F           ← localized strings, per language\n    │   └── de.lproj\u002F\n    ├── Frameworks\u002F             ← embedded .framework and .dylib — MUST be signed\n    ├── PlugIns\u002F                ← app extensions\n    ├── XPCServices\u002F            ← XPC helpers\n    ├── Library\u002F\n    │   └── LoginItems\u002F         ← helper apps registered via SMAppService\n    ├── _CodeSignature\u002F         ← signature over the whole bundle\n    └── embedded.provisionprofile (App Store \u002F some entitlements)\n```\n\n**Info.plist keys you will actually need:**\n| Key | Purpose |\n|---|---|\n| `CFBundleIdentifier` | Reverse-DNS identity. **Immutable in practice** — changing it orphans user data, keychain items, and the App Store record. |\n| `CFBundleShortVersionString` | Marketing version (\"2.1.0\") — what users see |\n| `CFBundleVersion` | Build number — must **monotonically increase** per upload |\n| `LSMinimumSystemVersion` | Minimum macOS |\n| `CFBundleDocumentTypes` \u002F `UTExportedTypeDeclarations` | File type ownership + custom UTIs |\n| `CFBundleURLTypes` | Custom URL schemes (`myapp:\u002F\u002F`) |\n| `NS*UsageDescription` | **Required** privacy strings — missing one = instant crash on first use of that API |\n| `LSUIElement` | `true` = menu-bar-only app, no Dock icon |\n| `LSApplicationCategoryType` | Required for the App Store |\n| `ITSAppUsesNonExemptEncryption` | Saves you an export-compliance dialog on every upload |\n\n> **⚠️ GOTCHA — missing usage strings crash, they don't warn.** Calling an API guarded by\n> TCC (camera, microphone, contacts, calendar, photos, Downloads\u002FDocuments\u002FDesktop,\n> screen recording, Automation\u002FAppleScript) without the corresponding\n> `NSCameraUsageDescription`-style key in Info.plist terminates the process immediately.\n> This looks like a random crash on a user's machine and is instant in the debugger.\n> Write the strings as user-facing sentences — the App Store rejects vague ones.\n\n**Where app data goes [PLATFORM]:**\n| Content | Sandboxed path | Non-sandboxed |\n|---|---|---|\n| User-visible documents | `~\u002FDocuments` via user selection | same |\n| App support \u002F databases | `~\u002FLibrary\u002FContainers\u002F\u003Cid>\u002FData\u002FLibrary\u002FApplication Support\u002F\u003Cid>` | `~\u002FLibrary\u002FApplication Support\u002F\u003Cid>` |\n| Caches (deletable) | `...\u002FLibrary\u002FCaches\u002F\u003Cid>` | `~\u002FLibrary\u002FCaches\u002F\u003Cid>` |\n| Preferences | `UserDefaults` → `...\u002FLibrary\u002FPreferences\u002F\u003Cid>.plist` | same |\n| Logs | `...\u002FLibrary\u002FLogs\u002F\u003Cid>` | `~\u002FLibrary\u002FLogs\u002F\u003Cid>` |\n\nUse `FileManager.default.url(for: .applicationSupportDirectory, in: .userDomainMask, ...)`\nand never hardcode paths — sandboxing silently redirects them, and hardcoded paths are the\n#1 reason an app breaks when you enable the sandbox.\n\n### 1.3 The run loop, GCD, and the main thread\n\n**[PLATFORM, but the concept is UNIVERSAL] All UI work happens on the main thread.**\nOn macOS the main thread runs an `NSRunLoop`\u002F`CFRunLoop` that dispatches events, timers,\nand sources. Touching `NSView`\u002F`NSWindow` — or SwiftUI state that a view reads — from any\nother thread is undefined behaviour that manifests as corrupted rendering or a crash in\nunrelated code minutes later.\n\n- **GCD (`DispatchQueue`)**: `DispatchQueue.main` is the UI queue. Background work goes on\n  `.global(qos:)` or a private serial queue. QoS classes (`.userInteractive`,\n  `.userInitiated`, `.utility`, `.background`) affect scheduling priority *and*\n  thermal\u002Fenergy behaviour — mislabeling background work as `.userInitiated` is a real\n  battery cost.\n- **Swift Concurrency** (`async`\u002F`await`, actors, `@MainActor`) is the modern layer over\n  this, and as of Swift 6 the compiler *enforces* the main-thread rule (§3.2).\n- **Thread explosion**: `DispatchQueue.concurrentPerform` and unbounded\n  `DispatchQueue.global().async` can blow past the thread limit and deadlock. Bound your\n  concurrency explicitly (semaphore, `TaskGroup` with a limit, or a serial queue).\n\n### 1.4 XPC — the right way to do privilege separation\n\nXPC is macOS's IPC mechanism, with lifecycle management by launchd. Use it for:\n- **Crash isolation**: a plugin host, a parser handling untrusted input, a video decoder.\n  If it crashes, the app survives.\n- **Privilege separation**: put the network- or file-parsing code in an XPC service with\n  a *tighter* sandbox than the main app. This is genuinely effective hardening.\n- **Privileged helpers**: `SMJobBless`-style root helpers (modern: `SMAppService.daemon`)\n  for the rare operation that truly needs root. Verify the *client's* code signature in\n  the helper — an unauthenticated root helper is a local privilege-escalation\n  vulnerability, and this has shipped in real products repeatedly.\n\n```swift\n\u002F\u002F Modern XPC with NSXPCConnection, plus the security check that people omit\nlet connection = NSXPCConnection(serviceName: \"com.example.MyApp.ParserService\")\nconnection.remoteObjectInterface = NSXPCInterface(with: ParsingProtocol.self)\nconnection.resume()\n\nlet proxy = connection.remoteObjectProxyWithErrorHandler { error in\n    \u002F\u002F Service crashed or was killed — degrade gracefully, don't crash the app\n    log.error(\"XPC failed: \\(error)\")\n} as? ParsingProtocol\n```\n\n### 1.5 Apple silicon, Rosetta, and universal binaries\n\n- Ship **universal 2** binaries (`arm64` + `x86_64`) via `lipo`\u002FXcode until you drop Intel.\n  **macOS 26 Tahoe is the last macOS to support Intel Macs** — from macOS 27, Apple\n  silicon only. That changes the calculus for new products: an arm64-only build is now\n  defensible for apps requiring macOS 27+.\n- **Rosetta 2** translates x86_64 ahead-of-time; it does *not* support AVX-512 and it\n  cannot load arm64 dylibs into an x86_64 process (or vice versa) — a mixed-architecture\n  plugin ecosystem is a real, painful problem.\n- Apple silicon has **efficiency and performance cores**; QoS is how you steer work\n  between them. Also relevant: unified memory means GPU\u002FCPU transfers are cheap, and\n  `MTLStorageMode.shared` is usually right.\n\n---\n\n## §2. macOS UI — SwiftUI and AppKit\n\n### 2.1 The 2026 state of play\n\n**[CONTESTED, and the most consequential macOS decision.]** The honest summary that\nexperienced Mac developers converge on: **almost nobody starts a new Mac app in pure\nAppKit anymore, and almost no serious Mac app is pure SwiftUI.** The real skill is knowing\nwhere the seam goes. Apple's own guidance (WWDC26 \"Use SwiftUI with AppKit and UIKit\") is\nexplicitly incremental: start new scenes in SwiftUI, keep existing AppKit, and there is\n*no expectation* that an app becomes entirely SwiftUI.\n\n**Case for SwiftUI on macOS:**\n- Declarative state→UI eliminates a whole category of \"view and model disagree\" bugs.\n- Dramatically less code for typical forms, lists, sidebars, settings.\n- One codebase across macOS\u002FiOS\u002FiPadOS\u002FvisionOS when that matters.\n- Apple's investment is entirely here; new APIs (including Liquid Glass adoption)\n  land in SwiftUI first or exclusively.\n- `@Observable` (the Observation framework) removed most of the `ObservableObject`\n  boilerplate and its over-invalidation problems.\n\n**Case for AppKit (still, in 2026):**\n- **Dense, large data.** `NSTableView`\u002F`NSOutlineView` with cell reuse still beat SwiftUI\n  `List`\u002F`Table` for tens of thousands of rows with complex cells. This is the single most\n  commonly cited gap.\n- **Deep menu, toolbar, and window customization** — non-native fullscreen, custom title\n  bars, accessory view controllers, `NSWindow` subclassing behaviours.\n- **Text.** `NSTextView`\u002FTextKit 2 is a full text system; SwiftUI's `TextEditor` is not\n  in the same category. Any editor, IDE, or writing app will use it.\n- **Precise control over first responder, key equivalents, and focus.**\n- **Backward deployment** to older macOS versions.\n- Predictability: AppKit does what you told it. SwiftUI sometimes does what it inferred.\n\n**The pragmatic architecture most shipping apps use:**\n```\nSwiftUI  → app structure (App\u002FScene), settings, sidebars, inspectors, simple lists,\n           anything form-shaped\nAppKit   → the one hard view (the editor, the canvas, the giant table), embedded via\n           NSViewRepresentable \u002F NSViewControllerRepresentable\nShared   → @Observable model layer that both read\n```\n\n### 2.2 SwiftUI on macOS — the Mac-specific parts\n\nThe parts of SwiftUI that only matter on the Mac, which iOS-shaped tutorials skip:\n\n```swift\n@main\nstruct MyApp: App {\n    @State private var model = AppModel()          \u002F\u002F @Observable, @MainActor\n\n    var body: some Scene {\n        \u002F\u002F A document-based app gets New\u002FOpen\u002FSave\u002FRevert\u002FVersions for free\n        DocumentGroup(newDocument: MyDocument()) { file in\n            EditorView(document: file.$document)\n        }\n        .commands {\n            \u002F\u002F Menu bar customization — Mac-only, and where most Mac apps live\n            CommandGroup(replacing: .newItem) {\n                Button(\"New Project…\") { model.newProject() }\n                    .keyboardShortcut(\"n\", modifiers: [.command, .shift])\n            }\n            CommandMenu(\"Analyze\") {\n                Button(\"Run\") { model.run() }.keyboardShortcut(\"r\")\n                Divider()\n                Button(\"Clear Results\") { model.clear() }\n                    .disabled(model.results.isEmpty)     \u002F\u002F menu items MUST disable\n            }\n        }\n\n        \u002F\u002F Settings scene → gets the standard ⌘, shortcut and window chrome\n        Settings { SettingsView().frame(width: 520) }\n\n        \u002F\u002F A secondary utility window, openable via openWindow(id:)\n        Window(\"Activity\", id: \"activity\") { ActivityView() }\n            .defaultSize(width: 400, height: 300)\n            .keyboardShortcut(\"0\", modifiers: .command)\n\n        \u002F\u002F Menu bar extra — the Mac's status-item idiom\n        MenuBarExtra(\"Status\", systemImage: \"waveform\") {\n            StatusMenu()\n        }\n        .menuBarExtraStyle(.window)   \u002F\u002F .menu for a plain menu, .window for a popover\n    }\n}\n\n\u002F\u002F Standard Mac three-column layout\nstruct RootView: View {\n    var body: some View {\n        NavigationSplitView {\n            Sidebar()\n        } content: {\n            ItemList()\n        } detail: {\n            DetailView()\n        }\n        .toolbar { \u002F* ... *\u002F }\n        .navigationSplitViewStyle(.balanced)\n    }\n}\n```\n\n**Mac-specific view modifiers worth knowing**: `.focusedSceneValue` (drive menu enablement\nfrom the focused window's state — this is how you make menu items correctly gray out),\n`.onKeyPress`, `.contextMenu`, `.draggable`\u002F`.dropDestination`, `.fileExporter`\u002F\n`.fileImporter` (they route through the sandbox correctly), `.help()` (tooltips),\n`.windowResizability`, `.defaultPosition`, `.presentedWindowToolbarStyle`.\n\n### 2.3 The interop seam — where the money is\n\n```swift\n\u002F\u002F Wrapping AppKit inside SwiftUI: the 90% case\nstruct TextEditorView: NSViewRepresentable {\n    @Binding var text: String\n\n    func makeNSView(context: Context) -> NSScrollView {\n        let scroll = NSTextView.scrollableTextView()\n        let tv = scroll.documentView as! NSTextView\n        tv.delegate = context.coordinator\n        tv.isRichText = false\n        tv.font = .monospacedSystemFont(ofSize: 13, weight: .regular)\n        return scroll\n    }\n\n    func updateNSView(_ scroll: NSScrollView, context: Context) {\n        guard let tv = scroll.documentView as? NSTextView else { return }\n        \u002F\u002F ⚠️ Guard against feedback loops: only write if actually different,\n        \u002F\u002F or every keystroke round-trips and the cursor jumps to the end.\n        if tv.string != text { tv.string = text }\n    }\n\n    func makeCoordinator() -> Coordinator { Coordinator(self) }\n\n    final class Coordinator: NSObject, NSTextViewDelegate {\n        let parent: TextEditorView\n        init(_ p: TextEditorView) { parent = p }\n        func textDidChange(_ n: Notification) {\n            guard let tv = n.object as? NSTextView else { return }\n            parent.text = tv.string\n        }\n    }\n}\n\n\u002F\u002F Wrapping SwiftUI inside AppKit: the incremental-adoption direction\nlet host = NSHostingController(rootView: InspectorView(model: model))\nsplitViewController.addSplitViewItem(NSSplitViewItem(viewController: host))\n```\n\n> **⚠️ GOTCHA — the `updateNSView` feedback loop.** This is *the* interop bug. SwiftUI\n> calls `updateNSView` whenever any observed state changes; if you unconditionally write\n> to the AppKit view, and the AppKit view's delegate writes back to the binding, you get\n> an infinite loop or (more insidiously) a cursor that resets to position 0 on every\n> keystroke. Always compare before assigning, and consider a \"programmatic change\" flag.\n\n> **⚠️ GOTCHA — sizing.** `NSViewRepresentable` doesn't automatically communicate an\n> intrinsic size to SwiftUI's layout. Set `intrinsicContentSize` on the NSView, or use\n> `.frame()` \u002F `sizeThatFits` explicitly, or you'll get a zero-height view and conclude\n> the wrapper is broken.\n\n### 2.4 Liquid Glass (macOS 26 Tahoe)\n\nmacOS 26 introduced **Liquid Glass**, the biggest visual change since 2013 — a translucent,\nlight-refracting material applied to toolbars, sidebars, menu bar, Dock, window controls,\nsheets, and popovers. What developers need to know:\n\n- **You get most of it for free.** Recompile against the macOS 26 SDK and framework-provided\n  chrome (toolbars, sidebars, sheets, popovers, standard controls) adopts the new material\n  with no code changes, whether you're on SwiftUI, UIKit, or AppKit.\n- **Custom components do not.** Anything you drew yourself keeps its old look and will\n  now clash. This is where the actual migration work is.\n- The opt-in APIs are `.glassEffect()`, `GlassEffectContainer`, and `glassEffectID` for\n  morphing between glass elements.\n- **Icons** need rework through Apple's **Icon Composer** (layered vector content with\n  blur\u002Ftranslucency, real-time specular highlights) — the old flat 1024px PNG workflow is\n  obsolete.\n- **[UNIVERSAL, and important]** Translucency is an accessibility hazard. Respect\n  **Reduce Transparency** and **Increase Contrast**; test with both on. Text over a\n  glass material at low contrast is a real WCAG failure, not a style preference.\n\n**[CONTESTED]** Whether to adopt aggressively: proponents argue apps that don't adapt will\nlook broken beside system apps; skeptics note the material is expensive to render, hurts\nlegibility when misapplied, and that Apple's own first-year implementations drew\nsubstantial criticism. The defensible middle: adopt the *system* chrome (free), use\nsemantic colors and system materials rather than hardcoded palettes, and be conservative\nabout applying `.glassEffect()` to your own content surfaces.\n\n### 2.5 Mac Catalyst — when (not) to use it\n\nCatalyst runs a UIKit iPad app on the Mac. **Its purpose is porting an existing iPad app**,\nand that's the only case where it's the right call. For a new multiplatform product, a\nSwiftUI multiplatform target produces a better Mac app for the same effort. Note also that\nApple silicon Macs can simply *run* unmodified iPad apps, which removes much of Catalyst's\noriginal motivation. Catalyst apps consistently read as \"not quite a Mac app\" to Mac users\n— wrong menu structure, wrong keyboard behaviour, wrong window resizing.\n\n---\n\n## §3. Swift, Concurrency, and Persistence\n\n### 3.1 Language baseline\n\n- **Swift 6.x is current** (Xcode 26.4 ships Swift 6.3; language *modes* 4\u002F4.2\u002F5\u002F6 are\n  selectable per target). Objective-C remains fully supported and is still load-bearing in\n  large codebases; new code should be Swift.\n- **`@Observable`** (Observation framework) replaced `ObservableObject`\u002F`@Published` for\n  most purposes: finer-grained invalidation (SwiftUI only re-renders views that read the\n  properties that actually changed), less boilerplate, no `objectWillChange` plumbing.\n- Value types by default; `struct` for models, `final class` when you need identity,\n  `actor` for shared mutable state.\n\n### 3.2 Swift 6 strict concurrency — the migration everyone is doing\n\nSwift 6 makes **data-race safety a compile-time guarantee**: warnings in Swift 5 mode\nbecome errors. Core concepts:\n\n| Concept | Meaning |\n|---|---|\n| `Sendable` | Marker protocol: values of this type can safely cross concurrency domains. Structs of Sendable members get it synthesized; classes only if immutable (`final` + all `let`) or internally synchronized. |\n| `actor` | Reference type with automatic mutual exclusion on its state. |\n| `@MainActor` | Global actor for UI. Everything touching views\u002Fview models belongs here. |\n| `nonisolated` | Opt a member out of its actor's isolation (must not touch isolated state). |\n| `nonisolated(unsafe)` | \"Trust me.\" Last resort; document why. |\n| `@preconcurrency` | Import a not-yet-audited module without drowning in errors. |\n\n```swift\n\u002F\u002F The canonical shapes.\n@MainActor @Observable\nfinal class DocumentViewModel {              \u002F\u002F UI state — main actor\n    var items: [Item] = []\n    var isLoading = false\n\n    private let store: ItemStore              \u002F\u002F an actor\n\n    func refresh() async {\n        isLoading = true\n        defer { isLoading = false }\n        items = await store.fetchAll()        \u002F\u002F compiler inserts the hop\n    }\n}\n\nactor ItemStore {                             \u002F\u002F shared mutable state — isolated\n    private var cache: [UUID: Item] = [:]\n    func fetchAll() -> [Item] { Array(cache.values) }\n    func insert(_ item: Item) { cache[item.id] = item }\n}\n\nstruct Item: Sendable, Identifiable {         \u002F\u002F crosses boundaries — must be Sendable\n    let id: UUID\n    var title: String\n}\n```\n\n**[IMPORTANT, and recent] Swift 6.2 changed the ergonomics substantially.** The\n\"approachable concurrency\" work (`SWIFT_APPROACHABLE_CONCURRENCY = YES`, on by default for\nnew Xcode 26 projects) **inverts the default**: code is main-actor-isolated unless you say\notherwise, and `nonisolated` async functions run on the *caller's* actor rather than\nhopping. `@concurrent` is the explicit escape hatch for pushing CPU-heavy work\n(decoding, image processing) off the main actor.\n\n**[CONTESTED]** Whether this is an improvement: proponents say the old model buried the\nsignal in a wall of Sendable errors and drove people to slap `@unchecked Sendable` on\neverything, so a safe-by-default model that's easy to use correctly is a net win.\nCritics — notably the \"Swift Concurrency is a Mess in 2026\" line of argument — say the\nrepeated model changes eroded trust, and that main-actor-by-default hides main-thread\nbottlenecks from developers who never learn to move work off it. Both observations are\naccurate; which dominates depends on team seniority.\n\n**Migration strategy that works** (from teams who've done it on 50K+ LOC):\n1. Stay in Swift 5 mode; turn on **complete** strict-concurrency *checking* to surface\n   warnings without breaking the build.\n2. Fix **module by module**, leaf-first. Flip each target to Swift 6 mode as it goes clean.\n3. Order of operations: `@MainActor` on view models and UI-adjacent classes → `Sendable`\n   on value types that cross boundaries → `actor` for shared mutable services → globals\n   last (`static let` + Sendable, or `@MainActor`, or as a last resort\n   `nonisolated(unsafe)` with a comment explaining the invariant).\n4. Expect a cascade: annotating one class forces its callers async, which forces theirs.\n   Budget real time; one documented migration touched 79 files and ~2,800 lines for a\n   mid-size app.\n\n> **⚠️ GOTCHA — the singleton.** `static var shared` is non-isolated global mutable state\n> and is an error in Swift 6. Fix with `static let` + `Sendable`, or `@MainActor static let`,\n> or convert the type to an `actor`. Do not reach for `nonisolated(unsafe)` first.\n\n### 3.3 Persistence on macOS\n\n| Option | Use when | Watch out for |\n|---|---|---|\n| **UserDefaults** | Small preferences, window state | Not for data. Not synchronized across processes reliably. |\n| **SwiftData** | New apps, macOS 14+\u002FiOS 17+, SwiftUI-shaped models | Younger; heavyweight\u002Fcustom migrations and some CloudKit sync modes still weak; measurable overhead at 10K+ rows |\n| **Core Data** | Existing apps, complex object graphs, 15+ entities, batch ops, older OS support | Verbose; concurrency model fights modern Swift; `.xcdatamodeld` is an Xcode-bound artifact |\n| **GRDB \u002F SQLiteData** | Data-heavy apps, you want SQL and control, fastest reads\u002Fbulk writes | More glue code for SwiftUI reactivity; no free CloudKit |\n| **Plain files (JSON\u002Fplist\u002FSQLite)** | Document-based apps, simple state | You own migration and atomicity |\n\n**[CONTESTED] SwiftData vs Core Data in 2026.** SwiftData is built on Core Data's storage\nengine and has been stable across three major OS releases; for new apps with SwiftUI it's\nthe productivity default. But real teams still choose Core Data for complex models — the\ncommon counterargument is roughly \"15 entities with intricate relationships, two decades\nof Core Data hardening versus three years of SwiftData, and the abstraction layer's\nstability doesn't automatically inherit the storage engine's.\" Both positions are held by\npeople shipping real apps. A third camp (growing) picks **GRDB** and skips the object\ngraph entirely.\n\n**[UNIVERSAL] Whatever you pick: design the migration story before v1 ships.** Desktop\napps hold years of irreplaceable user data. A schema you can't migrate is a product you\ncan't update.\n","# Desktop Apps (macOS & Linux): macOS Platform, SwiftUI\u002FAppKit, and Swift\n\n> **Part 1 of 5** of the *Desktop Application Programming — macOS & Linux* reference (plugin `desktop-apps-macos-linux`), covering §0–§3. Sibling skills: `desktop-linux-platform` (§4–§6), `desktop-cross-platform-and-architecture` (§7–§9), `desktop-packaging-security-and-testing` (§10–§13), `desktop-reference` (§14–§20). Section numbers are shared across the set; a reference written as §N → `skill` points into that sibling skill.\n>\n> **Currency:** Verified August 2026. See §18 → `desktop-reference` for the currency snapshot and what goes stale first.\n\n> **How to read this.** Reference, not tutorial. Sections are independent. Three markers:\n> - **[UNIVERSAL]** — true of desktop software regardless of platform or toolkit.\n> - **[PLATFORM]** — specific to macOS or a particular Linux stack. Verify against current docs.\n> - **[CONTESTED]** — competent engineers disagree. Both cases given; don't adjudicate for the reader.\n>\n> **⚠️ GOTCHA** boxes mark the failure modes that actually cost people days.\n>\n> **The single most important framing in this document:** macOS is *one* platform with\n> *one* vendor, *one* HIG, and *one* blessed path. Linux is *not a platform* — it is a\n> family of overlapping conventions (freedesktop specs), two dominant toolkits, two\n> display protocols, three packaging formats, and a dozen desktop environments. Advice\n> that treats them symmetrically is wrong. Almost every difficulty in cross-platform\n> desktop work traces back to this asymmetry.\n\n---\n\n## §0. Routing — Classify Before Answering\n\n### 0.1 The framework decision, up front\n\n| If the answer to this is yes... | ...then |\n|---|---|\n| macOS-only, deep OS integration, sold on the Mac App Store | **SwiftUI + AppKit** |\n| macOS + iOS from one codebase | **SwiftUI** (multiplatform target, not Catalyst) |\n| Linux-first, GNOME-native feel, will ship on Flathub | **GTK4 + libadwaita** |\n| Linux-first, KDE-native, or Linux+Windows+macOS with one native-ish toolkit | **Qt 6** |\n| Team is web developers; you already have a web app; deadline dominates | **Electron** |\n| Team can take on Rust; bundle size \u002F memory matter; want a small attack surface | **Tauri 2** |\n| Existing .NET\u002FWPF codebase and skills; need Linux | **Avalonia** |\n| Existing Kotlin\u002FAndroid codebase; JVM shop | **Compose Multiplatform** |\n| Pixel-identical custom UI on every OS, mobile too, don't care about native feel | **Flutter** |\n| It's a developer tool \u002F internal utility; native feel is irrelevant | Anything. Ship it. |\n\n**[UNIVERSAL] The framework decision is downstream of two questions people skip:**\n1. **Who maintains this in three years?** Framework choice is a hiring and staffing\n   decision more than a technical one. A \"better\" framework nobody on the team knows is\n   worse.\n2. **Does this app need to feel native, or merely to work?** These have completely\n   different cost curves. \"Feels native\" means platform menus, platform keyboard\n   conventions, platform file dialogs, platform accessibility, platform theming,\n   platform window behaviour — and it is 3–10× the work of \"works.\"\n\n### 0.2 The four architectures of a desktop app\n\n```\nA. Pure native, per platform     — two codebases, best feel, highest cost\nB. Native UI + shared core       — Rust\u002FC++\u002FGo core, SwiftUI on Mac, GTK\u002FQt on Linux\n                                   (the \"right\" answer for serious cross-platform apps)\nC. Single cross-platform toolkit — Qt \u002F Flutter \u002F Avalonia \u002F Compose. One UI, everywhere.\nD. Web UI in a shell            — Electron \u002F Tauri. One UI, everywhere, web tech.\n```\n**B is underrated.** Ghostty (Zig core + SwiftUI on macOS + GTK4 on Linux), 1Password\n(Rust core), Signal, and many others use it. The core is testable, portable, and\nperformance-critical; the UI is thin and idiomatic per platform. The cost is that you\nwrite the UI twice — but the UI is usually the *smaller* half of a serious application,\nand it's the half where \"twice\" buys you the most.\n\n### 0.3 The question-type router\n\n| Asked about... | Go to |\n|---|---|\n| Bundles, launchd, run loops, Darwin, XPC | §1 |\n| SwiftUI, AppKit, NSViewRepresentable, Liquid Glass, menus, windows | §2 |\n| Swift concurrency, @MainActor, SwiftData\u002FCore Data | §3 |\n| D-Bus, systemd user units, XDG specs, PipeWire, desktop files | §4 → `desktop-linux-platform` |\n| GTK4, libadwaita, Qt6, QML, toolkit choice on Linux | §5 → `desktop-linux-platform` |\n| Wayland, X11, XWayland, compositors, protocols | §6 → `desktop-linux-platform` |\n| Electron, Tauri, Flutter, Avalonia, Compose, Rust GUI | §7 → `desktop-cross-platform-and-architecture` |\n| MVVM, state management, undo, documents, IPC, threading | §8 → `desktop-cross-platform-and-architecture` |\n| Windows, keyboard, drag & drop, HiDPI, dark mode, i18n, a11y | §9 → `desktop-cross-platform-and-architecture` |\n| Notarization, DMG, Flatpak, Snap, AppImage, .deb\u002F.rpm, AppStream | §10 → `desktop-packaging-security-and-testing` |\n| Sparkle, auto-update, delta updates, rollout | §11 → `desktop-packaging-security-and-testing` |\n| TCC, entitlements, hardened runtime, portals, Electron security | §12 → `desktop-packaging-security-and-testing` |\n| UI testing, profiling, Instruments, sysprof, CI | §13 → `desktop-packaging-security-and-testing` |\n| \"Don't do this\" | §14 → `desktop-reference` |\n| \"Which is better, X or Y?\" | §15 → `desktop-reference` (contested) |\n| Books, docs, HIGs, authorities | §16 → `desktop-reference` |\n| Famous failures and lessons | §17 → `desktop-reference` |\n| \"Is this still current?\" | §18 → `desktop-reference` |\n\n---\n\n## §1. macOS Platform Architecture\n\n### 1.1 The stack\n\n```\n┌──────────────────────────────────────────────────┐\n│ Your app: SwiftUI \u002F AppKit \u002F Catalyst \u002F 3rd-party│\n├──────────────────────────────────────────────────┤\n│ App frameworks: AppKit, SwiftUI, UIKit(Catalyst) │\n├──────────────────────────────────────────────────┤\n│ Media\u002Fgraphics: Core Animation, Metal, Core Image,│\n│ AVFoundation, Core Text                          │\n├──────────────────────────────────────────────────┤\n│ Core Services: Foundation, Core Foundation, GCD, │\n│ Core Data, Network.framework, XPC                │\n├──────────────────────────────────────────────────┤\n│ Darwin: XNU kernel (Mach + BSD), launchd, dyld,  │\n│ APFS, Sandbox (Seatbelt), TCC, AMFI, SIP         │\n└──────────────────────────────────────────────────┘\n```\n\n**Things that matter and are non-obvious:**\n- **XNU is a hybrid kernel**: Mach (ports, IPC, VM, scheduling) + BSD (POSIX, sockets,\n  VFS). Mach ports are the substrate for XPC and for essentially all privileged IPC.\n- **launchd is PID 1** and the *only* supported way to run background processes. Not\n  cron, not init scripts, not a daemon you fork yourself.\n  - `LaunchAgents` run per-user in the GUI session (`~\u002FLibrary\u002FLaunchAgents`,\n    `\u002FLibrary\u002FLaunchAgents`). `LaunchDaemons` run as root, system-wide, with no GUI\n    session (`\u002FLibrary\u002FLaunchDaemons`).\n  - Modern apps should prefer **`SMAppService`** (macOS 13+) to register login items and\n    helpers from *inside* the app bundle, rather than dropping plists into\n    `~\u002FLibrary\u002FLaunchAgents`. The user then manages them in System Settings → General →\n    Login Items, which is what they expect.\n- **dyld** is the dynamic linker; the **dyld shared cache** is why system frameworks load\n  fast. `DYLD_*` environment variables are ignored for hardened-runtime and\n  SIP-protected processes — which is exactly why your `DYLD_LIBRARY_PATH` trick works in\n  development and fails in the notarized build.\n- **SIP (System Integrity Protection)** makes `\u002FSystem`, `\u002Fusr` (except `\u002Fusr\u002Flocal`),\n  and `\u002Fbin` immutable even to root. Never write outside `\u002Fusr\u002Flocal`, `\u002Fopt`, or the\n  app's own container.\n\n### 1.2 Bundles — the unit of macOS software\n\n```\nMyApp.app\u002F\n└── Contents\u002F\n    ├── Info.plist              ← identity, version, doc types, URL schemes, usage strings\n    ├── MacOS\u002F\n    │   └── MyApp               ← the actual executable (CFBundleExecutable)\n    ├── Resources\u002F\n    │   ├── Assets.car          ← compiled asset catalog (icons, images, colors)\n    │   ├── en.lproj\u002F           ← localized strings, per language\n    │   └── de.lproj\u002F\n    ├── Frameworks\u002F             ← embedded .framework and .dylib — MUST be signed\n    ├── PlugIns\u002F                ← app extensions\n    ├── XPCServices\u002F            ← XPC helpers\n    ├── Library\u002F\n    │   └── LoginItems\u002F         ← helper apps registered via SMAppService\n    ├── _CodeSignature\u002F         ← signature over the whole bundle\n    └── embedded.provisionprofile (App Store \u002F some entitlements)\n```\n\n**Info.plist keys you will actually need:**\n| Key | Purpose |\n|---|---|\n| `CFBundleIdentifier` | Reverse-DNS identity. **Immutable in practice** — changing it orphans user data, keychain items, and the App Store record. |\n| `CFBundleShortVersionString` | Marketing version (\"2.1.0\") — what users see |\n| `CFBundleVersion` | Build number — must **monotonically increase** per upload |\n| `LSMinimumSystemVersion` | Minimum macOS |\n| `CFBundleDocumentTypes` \u002F `UTExportedTypeDeclarations` | File type ownership + custom UTIs |\n| `CFBundleURLTypes` | Custom URL schemes (`myapp:\u002F\u002F`) |\n| `NS*UsageDescription` | **Required** privacy strings — missing one = instant crash on first use of that API |\n| `LSUIElement` | `true` = menu-bar-only app, no Dock icon |\n| `LSApplicationCategoryType` | Required for the App Store |\n| `ITSAppUsesNonExemptEncryption` | Saves you an export-compliance dialog on every upload |\n\n> **⚠️ GOTCHA — missing usage strings crash, they don't warn.** Calling an API guarded by\n> TCC (camera, microphone, contacts, calendar, photos, Downloads\u002FDocuments\u002FDesktop,\n> screen recording, Automation\u002FAppleScript) without the corresponding\n> `NSCameraUsageDescription`-style key in Info.plist terminates the process immediately.\n> This looks like a random crash on a user's machine and is instant in the debugger.\n> Write the strings as user-facing sentences — the App Store rejects vague ones.\n\n**Where app data goes [PLATFORM]:**\n| Content | Sandboxed path | Non-sandboxed |\n|---|---|---|\n| User-visible documents | `~\u002FDocuments` via user selection | same |\n| App support \u002F databases | `~\u002FLibrary\u002FContainers\u002F\u003Cid>\u002FData\u002FLibrary\u002FApplication Support\u002F\u003Cid>` | `~\u002FLibrary\u002FApplication Support\u002F\u003Cid>` |\n| Caches (deletable) | `...\u002FLibrary\u002FCaches\u002F\u003Cid>` | `~\u002FLibrary\u002FCaches\u002F\u003Cid>` |\n| Preferences | `UserDefaults` → `...\u002FLibrary\u002FPreferences\u002F\u003Cid>.plist` | same |\n| Logs | `...\u002FLibrary\u002FLogs\u002F\u003Cid>` | `~\u002FLibrary\u002FLogs\u002F\u003Cid>` |\n\nUse `FileManager.default.url(for: .applicationSupportDirectory, in: .userDomainMask, ...)`\nand never hardcode paths — sandboxing silently redirects them, and hardcoded paths are the\n#1 reason an app breaks when you enable the sandbox.\n\n### 1.3 The run loop, GCD, and the main thread\n\n**[PLATFORM, but the concept is UNIVERSAL] All UI work happens on the main thread.**\nOn macOS the main thread runs an `NSRunLoop`\u002F`CFRunLoop` that dispatches events, timers,\nand sources. Touching `NSView`\u002F`NSWindow` — or SwiftUI state that a view reads — from any\nother thread is undefined behaviour that manifests as corrupted rendering or a crash in\nunrelated code minutes later.\n\n- **GCD (`DispatchQueue`)**: `DispatchQueue.main` is the UI queue. Background work goes on\n  `.global(qos:)` or a private serial queue. QoS classes (`.userInteractive`,\n  `.userInitiated`, `.utility`, `.background`) affect scheduling priority *and*\n  thermal\u002Fenergy behaviour — mislabeling background work as `.userInitiated` is a real\n  battery cost.\n- **Swift Concurrency** (`async`\u002F`await`, actors, `@MainActor`) is the modern layer over\n  this, and as of Swift 6 the compiler *enforces* the main-thread rule (§3.2).\n- **Thread explosion**: `DispatchQueue.concurrentPerform` and unbounded\n  `DispatchQueue.global().async` can blow past the thread limit and deadlock. Bound your\n  concurrency explicitly (semaphore, `TaskGroup` with a limit, or a serial queue).\n\n### 1.4 XPC — the right way to do privilege separation\n\nXPC is macOS's IPC mechanism, with lifecycle management by launchd. Use it for:\n- **Crash isolation**: a plugin host, a parser handling untrusted input, a video decoder.\n  If it crashes, the app survives.\n- **Privilege separation**: put the network- or file-parsing code in an XPC service with\n  a *tighter* sandbox than the main app. This is genuinely effective hardening.\n- **Privileged helpers**: `SMJobBless`-style root helpers (modern: `SMAppService.daemon`)\n  for the rare operation that truly needs root. Verify the *client's* code signature in\n  the helper — an unauthenticated root helper is a local privilege-escalation\n  vulnerability, and this has shipped in real products repeatedly.\n\n```swift\n\u002F\u002F Modern XPC with NSXPCConnection, plus the security check that people omit\nlet connection = NSXPCConnection(serviceName: \"com.example.MyApp.ParserService\")\nconnection.remoteObjectInterface = NSXPCInterface(with: ParsingProtocol.self)\nconnection.resume()\n\nlet proxy = connection.remoteObjectProxyWithErrorHandler { error in\n    \u002F\u002F Service crashed or was killed — degrade gracefully, don't crash the app\n    log.error(\"XPC failed: \\(error)\")\n} as? ParsingProtocol\n```\n\n### 1.5 Apple silicon, Rosetta, and universal binaries\n\n- Ship **universal 2** binaries (`arm64` + `x86_64`) via `lipo`\u002FXcode until you drop Intel.\n  **macOS 26 Tahoe is the last macOS to support Intel Macs** — from macOS 27, Apple\n  silicon only. That changes the calculus for new products: an arm64-only build is now\n  defensible for apps requiring macOS 27+.\n- **Rosetta 2** translates x86_64 ahead-of-time; it does *not* support AVX-512 and it\n  cannot load arm64 dylibs into an x86_64 process (or vice versa) — a mixed-architecture\n  plugin ecosystem is a real, painful problem.\n- Apple silicon has **efficiency and performance cores**; QoS is how you steer work\n  between them. Also relevant: unified memory means GPU\u002FCPU transfers are cheap, and\n  `MTLStorageMode.shared` is usually right.\n\n---\n\n## §2. macOS UI — SwiftUI and AppKit\n\n### 2.1 The 2026 state of play\n\n**[CONTESTED, and the most consequential macOS decision.]** The honest summary that\nexperienced Mac developers converge on: **almost nobody starts a new Mac app in pure\nAppKit anymore, and almost no serious Mac app is pure SwiftUI.** The real skill is knowing\nwhere the seam goes. Apple's own guidance (WWDC26 \"Use SwiftUI with AppKit and UIKit\") is\nexplicitly incremental: start new scenes in SwiftUI, keep existing AppKit, and there is\n*no expectation* that an app becomes entirely SwiftUI.\n\n**Case for SwiftUI on macOS:**\n- Declarative state→UI eliminates a whole category of \"view and model disagree\" bugs.\n- Dramatically less code for typical forms, lists, sidebars, settings.\n- One codebase across macOS\u002FiOS\u002FiPadOS\u002FvisionOS when that matters.\n- Apple's investment is entirely here; new APIs (including Liquid Glass adoption)\n  land in SwiftUI first or exclusively.\n- `@Observable` (the Observation framework) removed most of the `ObservableObject`\n  boilerplate and its over-invalidation problems.\n\n**Case for AppKit (still, in 2026):**\n- **Dense, large data.** `NSTableView`\u002F`NSOutlineView` with cell reuse still beat SwiftUI\n  `List`\u002F`Table` for tens of thousands of rows with complex cells. This is the single most\n  commonly cited gap.\n- **Deep menu, toolbar, and window customization** — non-native fullscreen, custom title\n  bars, accessory view controllers, `NSWindow` subclassing behaviours.\n- **Text.** `NSTextView`\u002FTextKit 2 is a full text system; SwiftUI's `TextEditor` is not\n  in the same category. Any editor, IDE, or writing app will use it.\n- **Precise control over first responder, key equivalents, and focus.**\n- **Backward deployment** to older macOS versions.\n- Predictability: AppKit does what you told it. SwiftUI sometimes does what it inferred.\n\n**The pragmatic architecture most shipping apps use:**\n```\nSwiftUI  → app structure (App\u002FScene), settings, sidebars, inspectors, simple lists,\n           anything form-shaped\nAppKit   → the one hard view (the editor, the canvas, the giant table), embedded via\n           NSViewRepresentable \u002F NSViewControllerRepresentable\nShared   → @Observable model layer that both read\n```\n\n### 2.2 SwiftUI on macOS — the Mac-specific parts\n\nThe parts of SwiftUI that only matter on the Mac, which iOS-shaped tutorials skip:\n\n```swift\n@main\nstruct MyApp: App {\n    @State private var model = AppModel()          \u002F\u002F @Observable, @MainActor\n\n    var body: some Scene {\n        \u002F\u002F A document-based app gets New\u002FOpen\u002FSave\u002FRevert\u002FVersions for free\n        DocumentGroup(newDocument: MyDocument()) { file in\n            EditorView(document: file.$document)\n        }\n        .commands {\n            \u002F\u002F Menu bar customization — Mac-only, and where most Mac apps live\n            CommandGroup(replacing: .newItem) {\n                Button(\"New Project…\") { model.newProject() }\n                    .keyboardShortcut(\"n\", modifiers: [.command, .shift])\n            }\n            CommandMenu(\"Analyze\") {\n                Button(\"Run\") { model.run() }.keyboardShortcut(\"r\")\n                Divider()\n                Button(\"Clear Results\") { model.clear() }\n                    .disabled(model.results.isEmpty)     \u002F\u002F menu items MUST disable\n            }\n        }\n\n        \u002F\u002F Settings scene → gets the standard ⌘, shortcut and window chrome\n        Settings { SettingsView().frame(width: 520) }\n\n        \u002F\u002F A secondary utility window, openable via openWindow(id:)\n        Window(\"Activity\", id: \"activity\") { ActivityView() }\n            .defaultSize(width: 400, height: 300)\n            .keyboardShortcut(\"0\", modifiers: .command)\n\n        \u002F\u002F Menu bar extra — the Mac's status-item idiom\n        MenuBarExtra(\"Status\", systemImage: \"waveform\") {\n            StatusMenu()\n        }\n        .menuBarExtraStyle(.window)   \u002F\u002F .menu for a plain menu, .window for a popover\n    }\n}\n\n\u002F\u002F Standard Mac three-column layout\nstruct RootView: View {\n    var body: some View {\n        NavigationSplitView {\n            Sidebar()\n        } content: {\n            ItemList()\n        } detail: {\n            DetailView()\n        }\n        .toolbar { \u002F* ... *\u002F }\n        .navigationSplitViewStyle(.balanced)\n    }\n}\n```\n\n**Mac-specific view modifiers worth knowing**: `.focusedSceneValue` (drive menu enablement\nfrom the focused window's state — this is how you make menu items correctly gray out),\n`.onKeyPress`, `.contextMenu`, `.draggable`\u002F`.dropDestination`, `.fileExporter`\u002F\n`.fileImporter` (they route through the sandbox correctly), `.help()` (tooltips),\n`.windowResizability`, `.defaultPosition`, `.presentedWindowToolbarStyle`.\n\n### 2.3 The interop seam — where the money is\n\n```swift\n\u002F\u002F Wrapping AppKit inside SwiftUI: the 90% case\nstruct TextEditorView: NSViewRepresentable {\n    @Binding var text: String\n\n    func makeNSView(context: Context) -> NSScrollView {\n        let scroll = NSTextView.scrollableTextView()\n        let tv = scroll.documentView as! NSTextView\n        tv.delegate = context.coordinator\n        tv.isRichText = false\n        tv.font = .monospacedSystemFont(ofSize: 13, weight: .regular)\n        return scroll\n    }\n\n    func updateNSView(_ scroll: NSScrollView, context: Context) {\n        guard let tv = scroll.documentView as? NSTextView else { return }\n        \u002F\u002F ⚠️ Guard against feedback loops: only write if actually different,\n        \u002F\u002F or every keystroke round-trips and the cursor jumps to the end.\n        if tv.string != text { tv.string = text }\n    }\n\n    func makeCoordinator() -> Coordinator { Coordinator(self) }\n\n    final class Coordinator: NSObject, NSTextViewDelegate {\n        let parent: TextEditorView\n        init(_ p: TextEditorView) { parent = p }\n        func textDidChange(_ n: Notification) {\n            guard let tv = n.object as? NSTextView else { return }\n            parent.text = tv.string\n        }\n    }\n}\n\n\u002F\u002F Wrapping SwiftUI inside AppKit: the incremental-adoption direction\nlet host = NSHostingController(rootView: InspectorView(model: model))\nsplitViewController.addSplitViewItem(NSSplitViewItem(viewController: host))\n```\n\n> **⚠️ GOTCHA — the `updateNSView` feedback loop.** This is *the* interop bug. SwiftUI\n> calls `updateNSView` whenever any observed state changes; if you unconditionally write\n> to the AppKit view, and the AppKit view's delegate writes back to the binding, you get\n> an infinite loop or (more insidiously) a cursor that resets to position 0 on every\n> keystroke. Always compare before assigning, and consider a \"programmatic change\" flag.\n\n> **⚠️ GOTCHA — sizing.** `NSViewRepresentable` doesn't automatically communicate an\n> intrinsic size to SwiftUI's layout. Set `intrinsicContentSize` on the NSView, or use\n> `.frame()` \u002F `sizeThatFits` explicitly, or you'll get a zero-height view and conclude\n> the wrapper is broken.\n\n### 2.4 Liquid Glass (macOS 26 Tahoe)\n\nmacOS 26 introduced **Liquid Glass**, the biggest visual change since 2013 — a translucent,\nlight-refracting material applied to toolbars, sidebars, menu bar, Dock, window controls,\nsheets, and popovers. What developers need to know:\n\n- **You get most of it for free.** Recompile against the macOS 26 SDK and framework-provided\n  chrome (toolbars, sidebars, sheets, popovers, standard controls) adopts the new material\n  with no code changes, whether you're on SwiftUI, UIKit, or AppKit.\n- **Custom components do not.** Anything you drew yourself keeps its old look and will\n  now clash. This is where the actual migration work is.\n- The opt-in APIs are `.glassEffect()`, `GlassEffectContainer`, and `glassEffectID` for\n  morphing between glass elements.\n- **Icons** need rework through Apple's **Icon Composer** (layered vector content with\n  blur\u002Ftranslucency, real-time specular highlights) — the old flat 1024px PNG workflow is\n  obsolete.\n- **[UNIVERSAL, and important]** Translucency is an accessibility hazard. Respect\n  **Reduce Transparency** and **Increase Contrast**; test with both on. Text over a\n  glass material at low contrast is a real WCAG failure, not a style preference.\n\n**[CONTESTED]** Whether to adopt aggressively: proponents argue apps that don't adapt will\nlook broken beside system apps; skeptics note the material is expensive to render, hurts\nlegibility when misapplied, and that Apple's own first-year implementations drew\nsubstantial criticism. The defensible middle: adopt the *system* chrome (free), use\nsemantic colors and system materials rather than hardcoded palettes, and be conservative\nabout applying `.glassEffect()` to your own content surfaces.\n\n### 2.5 Mac Catalyst — when (not) to use it\n\nCatalyst runs a UIKit iPad app on the Mac. **Its purpose is porting an existing iPad app**,\nand that's the only case where it's the right call. For a new multiplatform product, a\nSwiftUI multiplatform target produces a better Mac app for the same effort. Note also that\nApple silicon Macs can simply *run* unmodified iPad apps, which removes much of Catalyst's\noriginal motivation. Catalyst apps consistently read as \"not quite a Mac app\" to Mac users\n— wrong menu structure, wrong keyboard behaviour, wrong window resizing.\n\n---\n\n## §3. Swift, Concurrency, and Persistence\n\n### 3.1 Language baseline\n\n- **Swift 6.x is current** (Xcode 26.4 ships Swift 6.3; language *modes* 4\u002F4.2\u002F5\u002F6 are\n  selectable per target). Objective-C remains fully supported and is still load-bearing in\n  large codebases; new code should be Swift.\n- **`@Observable`** (Observation framework) replaced `ObservableObject`\u002F`@Published` for\n  most purposes: finer-grained invalidation (SwiftUI only re-renders views that read the\n  properties that actually changed), less boilerplate, no `objectWillChange` plumbing.\n- Value types by default; `struct` for models, `final class` when you need identity,\n  `actor` for shared mutable state.\n\n### 3.2 Swift 6 strict concurrency — the migration everyone is doing\n\nSwift 6 makes **data-race safety a compile-time guarantee**: warnings in Swift 5 mode\nbecome errors. Core concepts:\n\n| Concept | Meaning |\n|---|---|\n| `Sendable` | Marker protocol: values of this type can safely cross concurrency domains. Structs of Sendable members get it synthesized; classes only if immutable (`final` + all `let`) or internally synchronized. |\n| `actor` | Reference type with automatic mutual exclusion on its state. |\n| `@MainActor` | Global actor for UI. Everything touching views\u002Fview models belongs here. |\n| `nonisolated` | Opt a member out of its actor's isolation (must not touch isolated state). |\n| `nonisolated(unsafe)` | \"Trust me.\" Last resort; document why. |\n| `@preconcurrency` | Import a not-yet-audited module without drowning in errors. |\n\n```swift\n\u002F\u002F The canonical shapes.\n@MainActor @Observable\nfinal class DocumentViewModel {              \u002F\u002F UI state — main actor\n    var items: [Item] = []\n    var isLoading = false\n\n    private let store: ItemStore              \u002F\u002F an actor\n\n    func refresh() async {\n        isLoading = true\n        defer { isLoading = false }\n        items = await store.fetchAll()        \u002F\u002F compiler inserts the hop\n    }\n}\n\nactor ItemStore {                             \u002F\u002F shared mutable state — isolated\n    private var cache: [UUID: Item] = [:]\n    func fetchAll() -> [Item] { Array(cache.values) }\n    func insert(_ item: Item) { cache[item.id] = item }\n}\n\nstruct Item: Sendable, Identifiable {         \u002F\u002F crosses boundaries — must be Sendable\n    let id: UUID\n    var title: String\n}\n```\n\n**[IMPORTANT, and recent] Swift 6.2 changed the ergonomics substantially.** The\n\"approachable concurrency\" work (`SWIFT_APPROACHABLE_CONCURRENCY = YES`, on by default for\nnew Xcode 26 projects) **inverts the default**: code is main-actor-isolated unless you say\notherwise, and `nonisolated` async functions run on the *caller's* actor rather than\nhopping. `@concurrent` is the explicit escape hatch for pushing CPU-heavy work\n(decoding, image processing) off the main actor.\n\n**[CONTESTED]** Whether this is an improvement: proponents say the old model buried the\nsignal in a wall of Sendable errors and drove people to slap `@unchecked Sendable` on\neverything, so a safe-by-default model that's easy to use correctly is a net win.\nCritics — notably the \"Swift Concurrency is a Mess in 2026\" line of argument — say the\nrepeated model changes eroded trust, and that main-actor-by-default hides main-thread\nbottlenecks from developers who never learn to move work off it. Both observations are\naccurate; which dominates depends on team seniority.\n\n**Migration strategy that works** (from teams who've done it on 50K+ LOC):\n1. Stay in Swift 5 mode; turn on **complete** strict-concurrency *checking* to surface\n   warnings without breaking the build.\n2. Fix **module by module**, leaf-first. Flip each target to Swift 6 mode as it goes clean.\n3. Order of operations: `@MainActor` on view models and UI-adjacent classes → `Sendable`\n   on value types that cross boundaries → `actor` for shared mutable services → globals\n   last (`static let` + Sendable, or `@MainActor`, or as a last resort\n   `nonisolated(unsafe)` with a comment explaining the invariant).\n4. Expect a cascade: annotating one class forces its callers async, which forces theirs.\n   Budget real time; one documented migration touched 79 files and ~2,800 lines for a\n   mid-size app.\n\n> **⚠️ GOTCHA — the singleton.** `static var shared` is non-isolated global mutable state\n> and is an error in Swift 6. Fix with `static let` + `Sendable`, or `@MainActor static let`,\n> or convert the type to an `actor`. Do not reach for `nonisolated(unsafe)` first.\n\n### 3.3 Persistence on macOS\n\n| Option | Use when | Watch out for |\n|---|---|---|\n| **UserDefaults** | Small preferences, window state | Not for data. Not synchronized across processes reliably. |\n| **SwiftData** | New apps, macOS 14+\u002FiOS 17+, SwiftUI-shaped models | Younger; heavyweight\u002Fcustom migrations and some CloudKit sync modes still weak; measurable overhead at 10K+ rows |\n| **Core Data** | Existing apps, complex object graphs, 15+ entities, batch ops, older OS support | Verbose; concurrency model fights modern Swift; `.xcdatamodeld` is an Xcode-bound artifact |\n| **GRDB \u002F SQLiteData** | Data-heavy apps, you want SQL and control, fastest reads\u002Fbulk writes | More glue code for SwiftUI reactivity; no free CloudKit |\n| **Plain files (JSON\u002Fplist\u002FSQLite)** | Document-based apps, simple state | You own migration and atomicity |\n\n**[CONTESTED] SwiftData vs Core Data in 2026.** SwiftData is built on Core Data's storage\nengine and has been stable across three major OS releases; for new apps with SwiftUI it's\nthe productivity default. But real teams still choose Core Data for complex models — the\ncommon counterargument is roughly \"15 entities with intricate relationships, two decades\nof Core Data hardening versus three years of SwiftData, and the abstraction layer's\nstability doesn't automatically inherit the storage engine's.\" Both positions are held by\npeople shipping real apps. A third camp (growing) picks **GRDB** and skips the object\ngraph entirely.\n\n**[UNIVERSAL] Whatever you pick: design the migration story before v1 ships.** Desktop\napps hold years of irreplaceable user data. A schema you can't migrate is a product you\ncan't update.\n",{"name":5,"description":7},"develop","ae32736a1aabddabca5d2c96d665aa0ebc7d8700","src\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdesktop-apps-macos-linux\u002Fskills\u002Fdesktop-macos-platform",3,"https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey","https:\u002F\u002Fthe-vibey-project.github.io\u002Fvibey\u002F","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project","https:\u002F\u002Fvibewithadam.matthewsteinberger.com","freedom for software engineers","2026-11-15 05:47:42",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add the-vibey-project\u002Fvibey --skill desktop-macos-platform",{"tool":40,"command":41},"bunx","bunx skills add the-vibey-project\u002Fvibey --skill desktop-macos-platform",{"tool":43,"command":44},"pnpm","pnpm dlx skills add the-vibey-project\u002Fvibey --skill desktop-macos-platform","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdesktop-apps-macos-linux\u002Fskills\u002Fdesktop-macos-platform\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7AT1FQJAE1FQYAMDTF490Y4","white-paper-writing","Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks \"how should I structure this\" for a long-form document.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fwhite-paper-writing\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7AT16BJRJJKK2MASXRZS76G","prose-technical-mechanics","Use when editing or writing prose at a technical\u002Fmechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-technical-mechanics\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7AT0W9HT0ZZ9Y287NW99MR3","prose-mechanics","Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate\u002FJamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix \"AI-sounding\" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-mechanics\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7AT0KR635JX66X2X6F3E2CP","narrative-structure","Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or \"how should I structure this story\u002Fpitch\u002Fpresentation\" request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fnarrative-structure\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7AT0AKGW09NKKZDYBT8VRDE","legal-brief-writing","Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic\u002Fneurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Flegal-brief-writing\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7AT00VWPS4Q8B5VEMXX9NQT","journal-publishability-criteria","Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs\u002Fpaper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fjournal-publishability-criteria\u002FSKILL.md",[],[]]