reference push notifications

Architecture (shipped 2026-04-22)


Scheduled task (live-ea, nightly-consolidation, etc.)
  ↓ detects RED item
bash notify.sh "title" "message" "priority"
  ↓ reads NTFY_TOPIC from ~/Library/Application Support/SkyRun/.env
  ↓ HTTP POST
https://ntfy.sh/skyrun-joseph-{secret-topic}
  ↓ push via Apple push infrastructure
Joseph's iPhone — ntfy app delivers notification
  ↓ tap notification
https://brief.josephbowens.com (PWA loads in Safari)

Files

Helper: ~/Library/Application Support/SkyRun/notify.sh — takes title / message / priority, POSTs to ntfy
Topic secret: NTFY_TOPIC env var in ~/Library/Application Support/SkyRun/.env (chmod 600)
Log: ~/Library/Logs/skyrun-notify.log — every attempted notification + HTTP response code

Why ntfy.sh vs Web Push

ntfy.sh is a free, open-source push-notification service with a native iOS app. Chose it over full Web Push because:

Zero infrastructure (no VAPID keys, no service worker, no subscription management)
Works on any iOS with the ntfy app (no iOS 16.4+ PWA-install dependency)
30-min build vs 2-3 hour Web Push build
Tradeoff: requires installing the ntfy app once on iPhone

Future upgrade path: swap notify.sh for a Pages Function + Web Push if/when the ntfy app gets annoying. All callers use the same bash notify.sh interface — no skill changes required.

iPhone setup (one-time)

1. App Store → install ntfy (by Philipp Heckel, free, no sign-up) 2. Open ntfy → Subscribe to topic → enter: skyrun-joseph-5e7212721177 3. Optional: set custom icon for the topic (tap the topic → settings) 4. Allow notifications when prompted Done. Future push notifications arrive as standard iOS notifications.

What triggers a push (by skill)

`live-ea` (every 20 min business hours)

Active-deal prospect reply (Hadank, Weber, etc.) → high priority
Signed contract detected → urgent priority
Max 1 notification per run; max 3 per hour total

`nightly-consolidation` (11pm daily)

Sends ONE aggregate morning-brief summary push:

urgent if overall system health RED
high if RED BD items (active-deal replies, signed contracts pending)
default if YELLOW
SKIP if all GREEN

Future triggers (wire as needed)

Scout run completes with new HOT leads
DQ check flags an integrity issue
BV subscription resets
Rachel sends an email (high-priority person)

Priority → iOS behavior mapping

urgent — banner + sound + bypasses Do Not Disturb
high — banner + sound
default — banner only
low — silent banner
min — notification center only

Safety

notify.sh silent-fails on any error (no topic, no network, 5xx) — never blocks caller
Topic secret is 16-char random hex; anyone who guesses it could spam, but unlikely
ntfy.sh is free with no guaranteed uptime — if down, notifications just don't arrive
If topic ever leaks, rotate: generate new hex, update .env, re-subscribe in iPhone app

Testing

bash
bash "$HOME/Library/Application Support/SkyRun/notify.sh" "Test" "Hello from SkyRun" default
tail -1 ~/Library/Logs/skyrun-notify.log
Should see: YYYY-MM-DDTHH:MM:SSZ default [200] Test — Hello from SkyRun

Wiring status

✅ notify.sh deployed + tested
✅ live-ea SKILL updated with Step 7b push logic
✅ nightly-consolidation SKILL updated with Step 11 aggregate push
⏳ Joseph: install ntfy app + subscribe to topic skyrun-joseph-5e7212721177