diff --git a/Makefile b/Makefile
index ad713e88..5b92660c 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,7 @@ DART ?= dart
 DEVICE ?= macos
 APP_STORE_DART_DEFINE ?= --dart-define=XWORKMATE_APP_STORE=true
 
-.PHONY: help deps analyze test check format run build-linux build-macos build-ios-sim package-deb package-rpm package-linux package-mac install-mac clean build-go-core render-release-docs check-export-compliance
+.PHONY: help deps analyze test check format run open-macos-xcode build-linux build-macos build-ios-sim package-deb package-rpm package-linux package-mac install-mac clean build-go-core render-release-docs check-export-compliance
 
 help: ## Show available targets
 	@grep -E '^[a-zA-Z0-9_.-]+:.*?## ' Makefile | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "%-18s %s\n", $$1, $$2}'
@@ -33,6 +33,9 @@ render-release-docs: ## Render feature matrix, roadmap, release notes, and chang
 run: ## Run the app on a device or desktop target (DEVICE=macos by default)
 	$(FLUTTER) run -d $(DEVICE)
 
+open-macos-xcode: ## Open the supported macOS Xcode workspace entrypoint
+	open macos/Runner.xcworkspace
+
 build-linux: ## Build the Linux app in release mode
 	$(FLUTTER) build linux --release
 
diff --git a/README.md b/README.md
index 05ab8654..92282676 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,34 @@ flutter test
 flutter run -d macos
 ```
 
+## Xcode Run For macOS
+
+XWorkmate only supports launching the macOS app from the workspace entrypoint:
+
+```bash
+open macos/Runner.xcworkspace
+```
+
+If you prefer a repo-native shortcut, run:
+
+```bash
+make open-macos-xcode
+```
+
+In Xcode:
+
+- Select the shared `Runner` scheme.
+- Select `My Mac` as the destination.
+- Configure signing only on the `Runner` target.
+- Leave CocoaPods plugin targets under `Pods` alone. They appear in the workspace by design and are not app signing targets.
+
+For release builds, archives, and packaging, continue to use:
+
+```bash
+flutter build macos
+make build-macos
+```
+
 ## Downloads
 
 | Platform | Download |
diff --git a/macos/Podfile b/macos/Podfile
index a1b4f537..cc852b7c 100644
--- a/macos/Podfile
+++ b/macos/Podfile
@@ -44,6 +44,16 @@ post_install do |installer|
       "#{other_cflags} -Wno-ignored-attributes"
   end
 
+  normalize_system_framework_refs = lambda do |project|
+    project.files.each do |file|
+      next unless file.path&.include?('/System/Library/Frameworks/')
+      next unless file.path.include?('Platforms/MacOSX.platform/Developer/SDKs/')
+
+      file.path = "System/Library/Frameworks/#{File.basename(file.path)}"
+      file.source_tree = 'SDKROOT'
+    end
+  end
+
   installer.pods_project.targets.each do |target|
     flutter_additional_macos_build_settings(target)
     next unless target.name == 'mobile_scanner'
@@ -63,4 +73,7 @@ post_install do |installer|
     end
     aggregate_target.user_project.save
   end
+
+  normalize_system_framework_refs.call(installer.pods_project)
+  installer.pods_project.save
 end
diff --git a/macos/Podfile.lock b/macos/Podfile.lock
index 45638f64..967d88ad 100644
--- a/macos/Podfile.lock
+++ b/macos/Podfile.lock
@@ -54,6 +54,6 @@ SPEC CHECKSUMS:
   shared_preferences_foundation: 7036424c3d8ec98dfe75ff1667cb0cd531ec82bb
   super_native_extensions: c2795d6d9aedf4a79fae25cb6160b71b50549189
 
-PODFILE CHECKSUM: 40201a8bb5df74fb44955c0f840d026554c1116d
+PODFILE CHECKSUM: 4e2338e02c264ac0a178e66b19bb419d1371cf22
 
 COCOAPODS: 1.16.2
diff --git a/macos/Runner.xcodeproj/project.pbxproj b/macos/Runner.xcodeproj/project.pbxproj
index b309ca54..94e5fbf7 100644
--- a/macos/Runner.xcodeproj/project.pbxproj
+++ b/macos/Runner.xcodeproj/project.pbxproj
@@ -390,7 +390,7 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
-			shellScript = "if [[ \"${WORKSPACE_DIR:-}\" == *.xcodeproj ]]; then\n  echo \"error: XWorkmate macOS builds with CocoaPods plugins must be launched from macos/Runner.xcworkspace, not Runner.xcodeproj.\" >&2\n  echo \"error: Open macos/Runner.xcworkspace in Xcode or run 'flutter build macos' from the repository root.\" >&2\n  exit 1\nfi\n\"$FLUTTER_ROOT\"/packages/flutter_tools/bin/macos_assemble.sh && touch Flutter/ephemeral/tripwire";
+			shellScript = "if [[ \"${WORKSPACE_DIR:-}\" == *.xcodeproj ]]; then\n  echo \"error: XWorkmate macOS builds with CocoaPods plugins must be launched from macos/Runner.xcworkspace, not Runner.xcodeproj.\" >&2\n  echo \"error: Close this project, open macos/Runner.xcworkspace in Xcode, and build the shared Runner scheme for My Mac.\" >&2\n  echo \"error: Pods targets appearing in the workspace are expected. Only configure signing on the Runner target.\" >&2\n  echo \"error: For release packaging, run 'flutter build macos' from the repository root.\" >&2\n  exit 1\nfi\n\"$FLUTTER_ROOT\"/packages/flutter_tools/bin/macos_assemble.sh && touch Flutter/ephemeral/tripwire";
 		};
 		8E8C2A3EBAA3461603096C04 /* [CP] Check Pods Manifest.lock */ = {
 			isa = PBXShellScriptBuildPhase;