diff --git a/Sources/remindctl/Commands/AddCommand.swift b/Sources/remindctl/Commands/AddCommand.swift
index f1583e3..d257044 100644
--- a/Sources/remindctl/Commands/AddCommand.swift
+++ b/Sources/remindctl/Commands/AddCommand.swift
@@ -7,7 +7,11 @@ enum AddCommand {
     CommandSpec(
       name: "add",
       abstract: "Add a reminder",
-      discussion: "Provide a title as an argument or via --title.",
+      discussion: """
+        Provide a title as an argument or via --title.
+        --alarm schedules a notification; it does not enable the native Urgent toggle in Reminders.app.
+        EventKit does not expose Urgent. To enable it, use Reminders.app.
+        """,
       signature: CommandSignatures.withRuntimeFlags(
         CommandSignature(
           arguments: [
@@ -18,7 +22,9 @@ enum AddCommand {
             .make(label: "list", names: [.short("l"), .long("list")], help: "List name", parsing: .singleValue),
             .make(label: "listID", names: [.long("list-id")], help: "List ID or ID prefix", parsing: .singleValue),
             .make(label: "due", names: [.short("d"), .long("due")], help: "Due date", parsing: .singleValue),
-            .make(label: "alarm", names: [.short("a"), .long("alarm")], help: "Alarm date", parsing: .singleValue),
+            .make(
+              label: "alarm", names: [.short("a"), .long("alarm")], help: "Notification date", parsing: .singleValue
+            ),
             .make(
               label: "location",
               names: [.long("location")],
diff --git a/Sources/remindctl/Commands/EditCommand.swift b/Sources/remindctl/Commands/EditCommand.swift
index c25d44e..5fed562 100644
--- a/Sources/remindctl/Commands/EditCommand.swift
+++ b/Sources/remindctl/Commands/EditCommand.swift
@@ -7,7 +7,11 @@ enum EditCommand {
     CommandSpec(
       name: "edit",
       abstract: "Edit a reminder",
-      discussion: "Use an index or ID prefix from the show output.",
+      discussion: """
+        Use an index or ID prefix from the show output.
+        --alarm schedules a notification; it does not enable the native Urgent toggle in Reminders.app.
+        EventKit does not expose Urgent. To enable it, use Reminders.app.
+        """,
       signature: CommandSignatures.withRuntimeFlags(
         CommandSignature(
           arguments: [
@@ -20,7 +24,9 @@ enum EditCommand {
               label: "listID", names: [.long("list-id")], help: "Move to list by ID or ID prefix", parsing: .singleValue
             ),
             .make(label: "due", names: [.short("d"), .long("due")], help: "Set due date", parsing: .singleValue),
-            .make(label: "alarm", names: [.short("a"), .long("alarm")], help: "Set alarm date", parsing: .singleValue),
+            .make(
+              label: "alarm", names: [.short("a"), .long("alarm")], help: "Set notification date", parsing: .singleValue
+            ),
             .make(label: "notes", names: [.short("n"), .long("notes")], help: "Set notes", parsing: .singleValue),
             .make(
               label: "url",
diff --git a/docs/commands.md b/docs/commands.md
index 03f677c..86fc9f9 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -58,6 +58,8 @@ Useful `add` options:
 - `--leaving` changes a location trigger to leaving.
 - `--radius <meters>` adjusts the geofence radius.
 
+`--alarm` schedules a notification; it does not enable the native **Urgent** toggle in Reminders.app. EventKit does not expose Urgent, so `remindctl` cannot set it. Use `--alarm` for a notification, or enable Urgent directly in Reminders.app.
+
 ## Edit reminders
 
 ```bash
@@ -74,6 +76,7 @@ remindctl edit 4A83 --no-repeat
 If `add`, `edit`, or `complete` reports `Reminder is missing a calendar`, EventKit saved the reminder but returned it without its list. Check Reminders.app before retrying; this error does not roll back the saved change.
 
 Changing or clearing only the due date leaves every alarm unchanged. Explicit alarm edits preserve relative and location-based alarms while replacing or clearing absolute alarms.
+As with `add`, `edit --alarm` schedules a notification without enabling native Urgent. Set Urgent in Reminders.app.
 
 ## Lists