fix: clarify notification alarms and native Urgent

[steipete]

add --help and edit --help now explain that --alarm schedules a notification without enabling the native Urgent toggle, and direct users to Reminders.app to enable Urgent. Command documentation carries the same guidance. EventKit alarm behavior is unchanged.

Fixes #79 through the reporter's explicitly requested documentation fallback. The public EventKit SDK exposes notification alarms but no native Urgent property. Thanks @Amitdvl for reporting the missing CLI guidance; release-note credit is in #82, which lands last.

Validation: make check (92 tests, 93.8% core coverage), release build, actual add --help and edit --help output, docs build, and P2 branch autoreview all passed. CI: https://github.com/openclaw/remindctl/actions/runs/34104839155.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[steipete]

Verified head d6a56e987dde3e0fa266b123135f6276c8e26569 locally:

• make check: strict Swift/shell/workflow lint and all 92 tests passed; core coverage 93.8% (898/957 lines; gate 90%).
• make build: built the release CLI successfully.
• Real bin/remindctl add --help and bin/remindctl edit --help both print: --alarm schedules a notification; it does not enable the native Urgent toggle in Reminders.app. They also direct users to Reminders.app to enable Urgent.
• make docs-site: passed.
• P2 autoreview: clean for the committed branch against origin/main.

This completes #79's requested documentation fallback. There is no native Urgent flag because the public EventKit SDK does not expose that control. Release-note credit for @Amitdvl is in #82, which should land last.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 7, 2026, 5:19 AM ET / 09:19 UTC.

ClawSweeper review

What this changes

Clarifies add/edit help and command documentation that notification alarms do not enable Reminders.app’s native Urgent toggle.

Merge readiness

✅ Ready for maintainer review

This PR remains useful: the requested CLI guidance is absent from main and v0.3.5. The focused clarification satisfies the reporter’s documentation fallback, and no blocking defect was found.

Priority: P3
Reviewed head: d6a56e987dde3e0fa266b123135f6276c8e26569

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused clarification with directly relevant CLI verification and no blocking findings.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The exact-head verification comment reports running both built CLI help entrypoints and quotes the new guidance rendered from the changed command specifications; help output directly proves this patch’s behavior.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The exact-head verification comment reports running both built CLI help entrypoints and quotes the new guidance rendered from the changed command specifications; help output directly proves this patch’s behavior.
Evidence reviewed	7 items	Verified introduced scope: The pinned base-to-head diff changes only help strings in two commands and explanatory prose in docs/commands.md; parsing, persistence, permissions, and dependencies are unchanged. Production help path: CommandRouter handles --help before command execution, and HelpPrinter renders command discussion and option descriptions directly. The changed strings therefore reach both requested help entrypoints. Existing implementation boundary: Reminder creation adds EKAlarm objects, while editing delegates absolute-alarm replacement to ReminderAlarmMutation. README.md already distinguishes this supported behavior from native Urgent; the PR makes that distinction discoverable in command help.
Findings	None	None.
Security	None	None.

How this fits together

remindctl manages Apple Reminders through public EventKit APIs. Its command help explains available options before users create or edit reminders.

flowchart TD
  A[Command arguments] --> B{Help requested?}
  B -->|Yes| C[Add or edit help]
  C --> D[Notification and Urgent guidance]
  B -->|No| E[Reminder command]
  E --> F[EventKit notification alarm]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

None.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #79
Summary: This PR implements the linked issue’s explicitly requested documentation fallback.

Members:

• canonical: Feature request: support Apple's native Urgent toggle #79 - The open request defines the accepted CLI/docs fallback and is explicitly linked for closure by this PR.
• adjacent_distinct: docs: prepare 0.3.6 release notes #82 - The open release-note PR records this work but does not implement or replace it.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Keep command help consistent with the documented public-EventKit boundary and direct users to Reminders.app for native Urgent.

Do we have a high-confidence way to reproduce the issue?

Not applicable to a documentation clarification; source comparison establishes the missing guidance, and the supplied CLI output demonstrates it after the change.

Is this the best way to solve the issue?

Yes. Updating the existing help and command documentation satisfies the reporter’s accepted fallback without adding unsupported APIs or changing alarm behavior.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against b366b1449e63.

Labels

Label justifications:

• P3: This is a low-risk help and documentation clarification with no change to reminder operations.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The exact-head verification comment reports running both built CLI help entrypoints and quotes the new guidance rendered from the changed command specifications; help output directly proves this patch’s behavior.
• proof: sufficient: Contributor real behavior proof is sufficient. The exact-head verification comment reports running both built CLI help entrypoints and quotes the new guidance rendered from the changed command specifications; help output directly proves this patch’s behavior.

Evidence

What I checked:

• Verified introduced scope: The pinned base-to-head diff changes only help strings in two commands and explanatory prose in docs/commands.md; parsing, persistence, permissions, and dependencies are unchanged. (Sources/remindctl/Commands/AddCommand.swift:10, d6a56e987dde)
• Production help path: CommandRouter handles --help before command execution, and HelpPrinter renders command discussion and option descriptions directly. The changed strings therefore reach both requested help entrypoints. (Sources/remindctl/HelpPrinter.swift:38, d6a56e987dde)
• Existing implementation boundary: Reminder creation adds EKAlarm objects, while editing delegates absolute-alarm replacement to ReminderAlarmMutation. README.md already distinguishes this supported behavior from native Urgent; the PR makes that distinction discoverable in command help. (Sources/RemindCore/EventKitStore.swift:127, d6a56e987dde)
• Main and release comparison: Inspected main’s edit command and command documentation, plus v0.3.5’s add command. They retain the shorter help without the new Urgent explanation; existing README guidance does not replace the requested CLI clarification. (Sources/remindctl/Commands/AddCommand.swift:10, e7fad8c848a3)
• After-change CLI evidence: The captured comment identifies the exact reviewed head, reports running the built release CLI’s add --help and edit --help, and quotes the new notification-versus-Urgent output. This directly exercises the changed behavior. It also reports 92 passing tests and a successful docs build: fix: clarify notification alarms and native Urgent #80 (comment). These commands were not rerun during this read-only review. (d6a56e987dde)
• Requested fallback and release coordination: Feature request: support Apple's native Urgent toggle #79 explicitly accepts CLI/docs clarification if public APIs cannot expose Urgent. The open docs: prepare 0.3.6 release notes #82 collects release notes and says it should land after the implementation branches; it does not supersede this patch. The previous completed review recorded no findings or published rank-up moves.

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (1 earlier review cycle)

• reviewed 2026-09-07T09:15:34.976Z sha d6a56e9 :: needs maintainer review before merge. :: none