diff --git a/NucleicRemote/NucleicRemote/AppIntents/IntentError.swift b/NucleicRemote/NucleicRemote/AppIntents/IntentError.swift
new file mode 100644
index 0000000..fb71770
--- /dev/null
+++ b/NucleicRemote/NucleicRemote/AppIntents/IntentError.swift
@@ -0,0 +1,24 @@
+import AppIntents
+
+/// Friendly, spoken-safe failures for Nucleic's App Intents. The phone is a thin client with no
+/// local authority (docs/APP_INTENTS_OPPORTUNITIES §3.1): an intent that can't reach the paired
+/// Mac must fail *clean* with a dialog, never silently or with a raw error.
+enum IntentError: Error, CustomLocalizedStringResourceConvertible {
+    /// No live channel to any paired Mac (and none came up within the wait window).
+    case macUnreachable
+    /// Not paired with a Mac yet — nothing to act on.
+    case notPaired
+    /// The action needs `control` scope, which this device hasn't been granted.
+    case controlScopeRequired
+
+    var localizedStringResource: LocalizedStringResource {
+        switch self {
+        case .macUnreachable:
+            "Your Mac isn't reachable right now. Try again when it's online."
+        case .notPaired:
+            "Pair this iPhone with your Mac in Nucleic first."
+        case .controlScopeRequired:
+            "This device can view and approve, but isn't allowed to control sessions."
+        }
+    }
+}