Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,72 @@
+# iOS PWA Push Notification Testing Guide
+
+Debugging web push notifications for the shark game on iOS.
+
+## Setup
+
+1. Load the test page at https://shark.iamgmb.com/push-test.html
+2. Share -> "Add to Home Screen"
+3. Open from home screen (not from Safari browser tab)
+
+## Expected subscription flow
+
+```
+Browser supports push -> SW registered -> Permission granted -> Push subscribed -> Subscription sent to server
+```
+
+## If subscribe succeeds but banner is invisible
+
+The push opt-in `<div id="pushBanner" style="display:none">` is hardcoded hidden in HTML. The `showNotificationBanner()` function must call `banner.style.display = 'block'` — without this explicit line, the banner state variable changes but the UI never reveals the prompt.
+
+**Check:** Does `showNotificationBanner()` have `banner.style.display = 'block';` at the top of the function body?
+
+## iOS PWA push limitation
+
+PushManager is NOT available in Safari's browser tab on iOS. The `FAIL: No PushManager` error is expected behavior on iPhone Safari. The user MUST:**
+
+1. Tap Share -> "Add to Home Screen"
+2. Open from home screen (PWA mode, fullscreen, no URL bar)
+3. Then push subscription works via Apple Push Service (APNs)
+
+## Common subscription failures
+The `user_id` column has a FK constraint to `users.id`. Test subscriptions use `user_id: NULL` — ensure the column allows NULL and the subscribe-noauth endpoint passes NULL.
+
+Fix:
+```sql
+-- Rebuild table with nullable user_id
+CREATE TABLE push_subscriptions_new (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER,
+    endpoint TEXT NOT NULL UNIQUE,
+    p256dh TEXT NOT NULL,
+    auth TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now'))
+);
+INSERT INTO push_subscriptions_new SELECT * FROM push_subscriptions;
+DROP TABLE push_subscriptions;
+ALTER TABLE push_subscriptions_new RENAME TO push_subscriptions;
+```
+
+### Server rejected subscription
+Check that the subscribe-noauth endpoint exists and accepts the POST body:
+```json
+{"endpoint": "https://...", "p256dh": "...", "auth": "..."}
+```
+
+## Test send after subcription
+
+```bash
+curl -s -X POST https://shark.iamgmb.com/api/push/test \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Expected: `{"sent": 1}`
+Failure: `{"sent": 0}` — check journald for `Push test failed: ...`
+
+## Debugging database
+
+```bash
+sqlite3 /root/shark-game/backend/game.db "SELECT count(*) FROM push_subscriptions;"
+sqlite3 /root/shark-game/backend/game.db "SELECT id, endpoint FROM push_subscriptions;"
+```