moving back to github

1 files changed, 350 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..dc2c7e3
--- /dev/null
+++ b/README.org
@@ -0,0 +1,350 @@
+
+* *CHIME Heralds Imminent Events*
+
+Customizable org notifications for Emacs with visual alerts, audible chimes, and modeline display.
+
+** About
+
+CHIME (backronym: *CHIME Heralds Imminent Events*) provides notification support for your org-agenda events. Get visual notifications, a pleasant chime sound, and see your next upcoming event in your modeline.
+
+This is an updated and maintained fork of the abandoned [[https://github.com/akhramov/org-wild-notifier.el][org-wild-notifier]] project, renamed to CHIME with bug-fixes and new features.
+
+Note: while I've found this package to be quite reliable, it's still undergoing feature development and will be changing frequently. 
+
+** Features
+
+- *Visual notifications* with customizable alert times
+- *Audible chime sound* when notifications are displayed. 
+- *Modeline display* of next upcoming event with customizable lookahead
+- Multiple notification times per event (e.g., 5 minutes before and at event time)
+- Works with SCHEDULED and DEADLINE and plain timestamps
+- Supports repeating timestamps (=+1w=, =.+1d=, =++1w=)
+- Per-event notification customization via properties
+- Async background checking (runs every minute)
+- Configurable notification filtering by keywords and tags
+- [[tests/testing-strategy.org][Well-tested]], including with org-gcal
+
+** Installation
+
+This package is NOT YET available on MELPA.
+
+*** package-vc-install (Emacs 29+)
+
+#+BEGIN_SRC elisp
+(unless (package-installed-p 'chime)
+  (package-vc-install "https://github.com/cjennings/chime.el"))
+#+END_SRC
+
+*** use-package with :vc (Emacs 29+)
+
+#+BEGIN_SRC elisp
+(use-package chime
+  :vc (:url "https://github.com/cjennings/chime.el" :rev :newest)
+  :after (alert org-agenda)
+  :commands (chime-mode chime-check)
+  :bind ("C-c A" . chime-check)
+  :config
+  ;; Notification times: 5 minutes before and at event time
+  (setq chime-alert-time '(5 0))
+
+  ;; Chime sound
+  (setq chime-play-sound t)
+
+  ;; Modeline display
+  (setq chime-modeline-lookahead 30)
+  (setq chime-modeline-format " ⏰ %s")
+
+  ;; Notification settings
+  (setq chime-notification-title "Reminder")
+  (setq chime-alert-severity 'medium)
+
+  ;; Don't filter by TODO keywords - notify for all events
+  (setq chime-keyword-whitelist nil)
+  (setq chime-keyword-blacklist nil)
+
+  ;; Only notify for non-done items
+  (setq chime-predicate-blacklist
+        '(chime-done-keywords-predicate))
+
+  ;; Enable chime-mode automatically
+  (chime-mode 1))
+#+END_SRC
+
+*** Manual Installation (Recommended for Development)
+
+#+BEGIN_SRC elisp
+;; Add to load-path
+(add-to-list 'load-path "~/path/to/chime.el")
+
+;; Load and configure
+(require 'chime)
+#+END_SRC
+
+** Quick Start
+
+Minimal configuration:
+
+clone the package somewhere, then add 
+
+#+BEGIN_SRC elisp
+  (add-to-list 'load-path  "/path/to/chime.el/")
+  (require 'chime)
+
+  ;; Notify 5 minutes before and at event time
+  (setq chime-alert-time '(5 0))
+
+  ;; Enable notifications
+  (chime-mode 1)
+#+END_SRC
+
+** Configuration
+
+*** Alert Times
+
+Set when to receive notifications (in minutes before event):
+
+#+BEGIN_SRC elisp
+;; Single notification 10 minutes before
+(setq chime-alert-time 10)
+
+;; Multiple notifications: 10 min, 5 min, and at event time
+(setq chime-alert-time '(10 5 0))
+#+END_SRC
+
+*** Chime Sound
+
+Control the audible chime that plays when notifications appear:
+
+#+BEGIN_SRC elisp
+;; Enable/disable chime sound (default: t)
+(setq chime-play-sound t)
+
+;; Use custom sound file (defaults to bundled chime.wav)
+(setq chime-sound-file "/path/to/your/chime.wav")
+
+;; Disable sound, use system beep instead
+(setq chime-sound-file nil)
+#+END_SRC
+
+The package includes a pleasant chime sound in GPL-compatible WAV format. You can use your own sound file if preferred.
+
+*** Modeline Display
+
+Show the next upcoming event in your modeline:
+
+#+BEGIN_SRC elisp
+;; Show events up to 30 minutes ahead (default)
+(setq chime-modeline-lookahead 30)
+
+;; Customize the display format (default: " ⏰ %s")
+(setq chime-modeline-format " [Next: %s]")
+
+;; Disable modeline display
+(setq chime-modeline-lookahead 0)
+#+END_SRC
+
+The modeline will display the soonest event within the lookahead window, formatted as:
+- Default: =⏰ Meeting with Team at 02:30 PM (in 15 minutes)=
+- Updates automatically every minute
+
+*** Notification Settings
+
+#+BEGIN_SRC elisp
+;; Notification title
+(setq chime-notification-title "Reminder")
+
+;; Notification severity (low, medium, high)
+(setq chime-alert-severity 'medium)
+#+END_SRC
+
+*** Filtering
+
+#+BEGIN_SRC elisp
+;; Only notify for specific TODO keywords
+(setq chime-keyword-whitelist '("TODO" "NEXT"))
+
+;; Never notify for these keywords
+(setq chime-keyword-blacklist '("DONE" "CANCELLED"))
+
+;; Only notify for specific tags
+(setq chime-tags-whitelist '("@important"))
+
+;; Never notify for these tags
+(setq chime-tags-blacklist '("someday"))
+#+END_SRC
+
+** Usage
+
+*** Basic Event with Timestamp
+
+#+BEGIN_SRC org
+,* Meeting with Team
+<2025-10-25 Sat 14:00>
+#+END_SRC
+
+Will notify at 14:00 (if =chime-alert-time= includes =0=).
+
+*** Events with SCHEDULED or DEADLINE
+
+#+BEGIN_SRC org
+,* TODO Call Doctor
+SCHEDULED: <2025-10-25 Sat 10:00>
+#+END_SRC
+
+*** Repeating Events
+
+Repeating timestamps are fully supported:
+
+#+BEGIN_SRC org
+,* TODO Weekly Team Meeting
+SCHEDULED: <2025-10-25 Sat 14:00 +1w>
+
+,* TODO Daily Standup
+SCHEDULED: <2025-10-25 Sat 09:00 +1d>
+
+,* TODO Review Email
+SCHEDULED: <2025-10-25 Sat 08:00 .+1d>
+#+END_SRC
+
+Supported repeaters:
+- =+1w= - Repeat weekly from original date
+- =.+1d= - Repeat daily from completion
+- =++1w= - Repeat weekly from scheduled date
+
+*** Per-Event Notification Times
+
+Override global notification times for specific events:
+
+#+BEGIN_SRC org
+,* IMPORTANT Board Meeting
+SCHEDULED: <2025-10-25 Sat 14:00>
+:PROPERTIES:
+:CHIME_NOTIFY_BEFORE: 30 15 5 0
+:END:
+#+END_SRC
+
+This event will notify at: 30min, 15min, 5min before, and at event time.
+
+** Known Limitations
+
+*** Sexp Diary Entries Not Supported
+
+This format is *not supported*:
+
+#+BEGIN_SRC org
+,* TODO Daily Standup
+SCHEDULED: <%%(memq (calendar-day-of-week date) '(1 2 3 4 5))>
+#+END_SRC
+
+*Workaround:* Use standard repeating timestamps instead:
+
+#+BEGIN_SRC org
+,* TODO Daily Standup
+SCHEDULED: <2025-10-24 Fri 09:00 +1d>
+#+END_SRC
+
+For Monday-Friday events, you can either:
+1. Accept weekend notifications (mark as DONE on weekends)
+2. Create 5 separate entries, one for each weekday with =+1w= repeater
+
+** Full Example Configuration
+
+#+BEGIN_SRC elisp
+  (use-package chime
+    :vc (:url "https://github.com/cjennings/chime.el" :rev :newest)
+    :after (alert org-agenda)
+    :commands (chime-mode chime-check)
+    :config
+    ;; Notification times: 5 minutes before and at event time
+    (setq chime-alert-time '(5 0))
+
+    ;; Chime sound
+    (setq chime-play-sound t)
+    ;; Uses bundled chime.wav by default
+
+    ;; Modeline display
+    (setq chime-modeline-lookahead 120)   ;; notify for events 2 hrs ahead
+    (setq chime-modeline-format " ⏰ %s") 
+
+    ;; Notification settings
+    (setq chime-notification-title "Reminder")
+    (setq chime-alert-severity 'medium)
+
+    ;; Don't filter by TODO keywords - notify for all events
+    (setq chime-keyword-whitelist nil)
+    (setq chime-keyword-blacklist nil)
+
+    ;; Only notify for non-done items
+    (setq chime-predicate-blacklist
+          '(chime-done-keywords-predicate))
+
+    ;; Enable chime-mode automatically
+    (chime-mode 1))
+#+END_SRC
+
+** Manual Check
+
+You can manually trigger a notification check:
+
+#+BEGIN_SRC elisp
+M-x chime-check
+#+END_SRC
+
+** Troubleshooting
+
+*** No notifications appearing
+
+1. Verify chime-mode is enabled: =M-: chime-mode=
+2. Check that alert is configured correctly:
+   #+BEGIN_SRC elisp
+   (setq alert-default-style 'libnotify)  ; or 'notifications on some systems
+   #+END_SRC
+3. Manually test: =M-x chime-check=
+4. Check =*Messages*= buffer for error messages
+
+*** No sound playing
+
+1. Verify sound is enabled: =M-: chime-play-sound= should return =t=
+2. Check sound file exists: =M-: (file-exists-p chime-sound-file)=
+3. Test sound directly: =M-: (play-sound-file chime-sound-file)=
+4. Ensure your system has audio support configured
+
+*** Events not being detected
+
+1. Ensure files are in =org-agenda-files=
+2. Verify timestamps have time components: =<2025-10-25 Sat 14:00>= not =<2025-10-25 Sat>=
+3. Check filtering settings (keyword/tag whitelist/blacklist)
+
+** Requirements
+
+- Emacs 26.1+
+- Org-mode 9.0+
+- =alert= package
+- =dash= package
+- =async= package
+
+** License
+
+GPL-3.0
+
+** Credits
+
+All credit and thanks should go to Artem Khramov for his work on [[https://github.com/akhramov/org-wild-notifier.el][org-wild-notifier]]. Early in 2025, I needed an event notifier in Emacs and found this package. Sadly, the author deprecated org-wild-notifier on Aug 2, 2025 in favor of [[https://github.com/spegoraro/org-alert][org-alert]]. I began fixing bugs and enhancing the feature set into what I needed, then decided it had become different enough to name it CHIME. I plan to maintain this in appreciation and gratitude of Artem's work, and for the larger Emacs community. 
+
+** Migration from Org-Wild-Notifier
+
+If you're migrating from org-wild-notifier, you'll need to update your configuration:
+
+1. Change package name:
+   - =(require 'org-wild-notifier)= → =(require 'chime)=
+
+2. Update all configured variable names:
+   - =org-wild-notifier-*= → =chime-*=
+
+3. Update configured function names:
+   - =org-wild-notifier-mode= → =chime-mode=
+   - =org-wild-notifier-check= → =chime-check=
+
+4. Update property names in your org files:
+   - =:WILD_NOTIFIER_NOTIFY_BEFORE:= → =:CHIME_NOTIFY_BEFORE:=
+