From a2cf5c0af24ca11a7ab73f6fb710a40a67998f48 Mon Sep 17 00:00:00 2001
From: jfishman1 <jon@onesignal.com>
Date: Thu, 29 Oct 2026 15:39:16 -0700
Subject: [PATCH] fix: align Firebase guidance with the documented
 google-services.json recommendation

The skills told the agent that google-services.json is "NOT required" and
called the OneSignal docs recommending it "a known bug." That text came from
the July 31 vendor baseline (803f234), months before Android SDK 5.11.0
existed. It is no longer accurate.

What changed upstream: on 5.11.0+, when the host app has its own default
FirebaseApp whose sender ID and applicationId project number both match the
sender configured in OneSignal, push registers through the customer's Firebase
project instead of OneSignal's shared one. The docs now recommend
google-services.json for all new Android integrations, and require it when
firebase_messaging_installation_id_enabled is true in the merged manifest
(a dependency such as Braze 43.0.0+ can set it through manifest merging).

The agent's behavior barely changes: it still must not add the file, since it
cannot produce one -- that comes from the customer's Firebase console -- and
applying the Gradle plugin without a file to process fails the build. What
changes is the framing, that the agent now tells the user the file is
recommended rather than asserting it is unnecessary, and that it stops when
the FID manifest flag is set.

Skills updated: setup/android.md, setup/cross-platform.md (4 places),
setup/SKILL.md, credentials/SKILL.md, credentials/api-uploaded-credentials.md,
verify/SKILL.md, verify/platform-verification.md. references/platform-matrix.md
is updated too because setup/android.md defers to it; leaving it would have
made the two contradict.

verify_integration.py: android_no_stray_google_services warned whenever
google-services.json existed without other Firebase client usage -- exactly the
state of a project that followed the docs, so it flagged correct setups.
Replaced with android_google_services_plugin_without_file, which catches the
real build-breaking case: the Google Services plugin applied with no file to
process, which fails with "File google-services.json is missing." Raised from
warn to error because it breaks the build.

Touches setup/android.md in the Firebase section near the top of the file, away
from the composite-login region changed in #85. Applied cleanly to the pre-#85
base, so the two should not conflict.

Refs SDK-5427.
---
 references/platform-matrix.md                 |  2 +-
 scripts/verify_integration.py                 | 19 ++++++++++++-------
 skills/credentials/SKILL.md                   |  2 +-
 .../credentials/api-uploaded-credentials.md   |  2 +-
 skills/setup/SKILL.md                         |  2 +-
 skills/setup/android.md                       | 13 +++++++++++--
 skills/setup/cross-platform.md                |  8 ++++----
 skills/verify/SKILL.md                        |  2 +-
 skills/verify/platform-verification.md        |  2 +-
 9 files changed, 33 insertions(+), 19 deletions(-)

diff --git a/references/platform-matrix.md b/references/platform-matrix.md
index 59adc92..48f23d6 100644
--- a/references/platform-matrix.md
+++ b/references/platform-matrix.md
@@ -8,7 +8,7 @@ What the agent can do vs. what stays human, per platform. Verified against SDK r
 |---|---|---|---|
 | **Web** (most automatable) | `<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer>` + `OneSignal.init({appId})` via `OneSignalDeferred`; create `OneSignalSDKWorker.js` containing one line `importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");` placed in `public/` (maps to origin root on Next/CRA/Vite/Vue/Angular) | Dashboard web-platform config (Site URL must EXACTLY match origin); confirm deployed site serves the worker same-origin over HTTPS with `Content-Type: application/javascript` | **Signup/onboarding does NOT provision the web platform** — until the dashboard step happens the SDK fails init with `App not configured for web push` (sync `code: 2`); probe `GET /sync/{app_id}/web` (api-reference), or provision via the write-once credentials endpoint (`chrome_web_origin`). SW must be same-origin — no CDN/subdomain. Subdir placement needs `serviceWorkerPath` + `serviceWorkerParam.scope`. PWA conflict: only one SW per scope. localhost testing works with a separate app + `allowLocalhostAsSecureOrigin: true`. Frameworks: react-onesignal / onesignal-vue3 / onesignal-ngx npm packages. |
 | **Expo** (best mobile) | `npx expo install onesignal-expo-plugin` + `npm i react-native-onesignal`; app.json: plugin FIRST in plugins array, `mode`, `smallIcons`; init in `App.tsx`/`_layout.tsx` | Apple .p8 + Firebase JSON procurement; EAS credentials must match; dev build (push doesn't work in Expo Go) | Config plugin generates NSE, entitlements, App Group, UIBackgroundModes at prebuild — zero manual Xcode. Expo SDK 53+/RN 0.79+ New Architecture. |
-| **Android** | Gradle dep `com.onesignal:OneSignal:<exact Stable from releases.json>` (e.g. `5.9.1` — **exact pin, never a version range**); Application subclass with `OneSignal.initWithContext(this, APP_ID)`; register in AndroidManifest `android:name`; `requestPermission` call | Firebase console: create project (if none), generate **service-account JSON**; (agent uploads it via API) | **`google-services.json` is NOT required for OneSignal** — FCM v1 credentials are server-side only (the upstream ai-prompt requiring it is a known bug; only keep it if the app itself uses Firebase client SDKs). `POST_NOTIFICATIONS` is manifest-merged by the SDK — no edit. Play-services emulator OK for testing. **Version + Kotlin floor:** resolve the exact pin with `python3 scripts/resolve_sdk_version.py android` (never compose the line by hand — ranges break the build). The SDK's OpenTelemetry submodule transitively pulls a newer `kotlin-stdlib` than its POM admits (5.9.1 resolves to 2.2.20), so the host needs a Kotlin compiler that can read that metadata — check it with `python3 scripts/android_kotlin_check.py . --deps -` (fed a `:app:dependencies` run) and surface any required toolchain bump as a separately-approved change; never half-bump to a version still below the resolved stdlib. |
+| **Android** | Gradle dep `com.onesignal:OneSignal:<exact Stable from releases.json>` (e.g. `5.9.1` — **exact pin, never a version range**); Application subclass with `OneSignal.initWithContext(this, APP_ID)`; register in AndroidManifest `android:name`; `requestPermission` call | Firebase console: create project (if none), generate **service-account JSON**; (agent uploads it via API) | **`google-services.json` is not required for OneSignal** — FCM v1 credentials are server-side only — but it is **recommended on SDK 5.11.0+**, and **required** when `firebase_messaging_installation_id_enabled` is `true` in the merged manifest. The agent never adds or removes it (the user supplies it from the Firebase console); never apply the Gradle plugin without the file, which fails the build. `POST_NOTIFICATIONS` is manifest-merged by the SDK — no edit. Play-services emulator OK for testing. **Version + Kotlin floor:** resolve the exact pin with `python3 scripts/resolve_sdk_version.py android` (never compose the line by hand — ranges break the build). The SDK's OpenTelemetry submodule transitively pulls a newer `kotlin-stdlib` than its POM admits (5.9.1 resolves to 2.2.20), so the host needs a Kotlin compiler that can read that metadata — check it with `python3 scripts/android_kotlin_check.py . --deps -` (fed a `:app:dependencies` run) and surface any required toolchain bump as a separately-approved change; never half-bump to a version still below the resolved stdlib. |
 | **iOS native** | SPM (`OneSignal-XCFramework` repo, map `OneSignalFramework`→app) or Podfile; `OneSignal.initialize(appId, withLaunchOptions:)` in AppDelegate/adaptor; Info.plist `UIBackgroundModes remote-notification`; entitlements text; debug-only verification helper | Apple Developer portal: paid account, Push capability on App ID, generate **.p8** (+ Key ID/Team ID); Xcode GUI: signing, capabilities toggle, and **NSE target creation** (File>New>Target — not reliably text-editable); physical-device test (launch from Xcode) + the notification permission tap | NSE is OPTIONAL for minimal install (needed only for rich media / confirmed receipt / badges) — OneSignal's own AI prompt skips it. Never hardcode a fallback App ID. Remote push testing: physical device (human launches), or a simulator on an Apple-silicon Mac that the verify skill boots, installs, and launches itself via `simctl` (Xcode 14+ simulators there receive real sandbox APNs pushes; Intel-Mac simulators do not) — only the permission tap stays human. |
 | **React Native / Flutter / Cordova / Capacitor** | Package install (`react-native-onesignal` / `onesignal_flutter` / `onesignal-cordova-plugin` / `@onesignal/capacitor-plugin` + `npx cap sync` — exact Stable version from releases.json, no ranges/carets); init call in entry file; Podfile NSE pod line; version bumps (RN 0.79+ New Arch, Flutter 3.29+) | Everything in the iOS-native human column (these wrappers inherit the full native iOS GUI flow); Firebase JSON procurement | Capacitor: set `ios.handleApplicationNotifications: false` in capacitor.config. Android side is handled by the wrapper plugins — no manual gradle/manifest edits documented. |
 | **Unity** | Init `OneSignal.Initialize("APP_ID")` in a MonoBehaviour; icon assets | GUI-bound install (Package Manager/Asset Store), Player Settings gradle-template toggles | Low human friction but low agent-automatability. Unity 2022.3+, Android API 33+. |
diff --git a/scripts/verify_integration.py b/scripts/verify_integration.py
index 280c16f..2be1427 100755
--- a/scripts/verify_integration.py
+++ b/scripts/verify_integration.py
@@ -252,13 +252,18 @@ def android_manifest_no_node_replace(self):
             ),
         )
 
-    def android_no_stray_google_services(self):
+    def android_google_services_plugin_without_file(self):
+        """The Gradle plugin without google-services.json fails the build.
+
+        The file alone is fine, and is recommended on SDK 5.11.0+, so its mere
+        presence is not a finding. Applying the plugin with no file to process
+        is, because the build fails with "File google-services.json is missing".
+        """
         gs = [fp for fp in walk_files(self.root) if os.path.basename(fp) == "google-services.json"]
-        firebase = grep(self.root, r"com\.google\.firebase")
-        # only a problem if google-services.json exists AND the app doesn't otherwise use Firebase
-        bad = bool(gs) and not firebase
-        self.add("android_no_stray_google_services", not bad, "warn",
-                 "" if not bad else "google-services.json present but no Firebase client usage — OneSignal does NOT require it")
+        plugin = grep(self.root, r"com\.google\.gms(\.|:)google-services")
+        bad = bool(plugin) and not gs
+        self.add("android_google_services_plugin_without_file", not bad, "error",
+                 "" if not bad else "com.google.gms.google-services is applied but no google-services.json was found \u2014 the build will fail. Add the file from the Firebase console, or remove the plugin.")
 
     def android_requestpermission_not_callback(self):
         # OneSignal.Notifications.requestPermission is `suspend fun(Boolean): Boolean`
@@ -589,7 +594,7 @@ def run(self):
         by_platform = {
             "android": [self.android_init_in_application, self.android_manifest_registers_app,
                         self.android_manifest_no_node_replace,
-                        self.android_no_stray_google_services, self.android_verification_debug_guarded,
+                        self.android_google_services_plugin_without_file, self.android_verification_debug_guarded,
                         self.android_requestpermission_not_callback, self.android_buildconfig_feature_enabled,
                         self.android_coroutines_on_classpath],
             # Unity ships via .unitypackage/UPM (a GUI step, no text manifest we can
diff --git a/skills/credentials/SKILL.md b/skills/credentials/SKILL.md
index ec6c1dd..ea90d8f 100644
--- a/skills/credentials/SKILL.md
+++ b/skills/credentials/SKILL.md
@@ -198,7 +198,7 @@ Full portal detail (enable-FCM-v1 detour, required service-account permissions,
 3. **Generate the key:** Project settings → **Service accounts** → **Generate new private key** → confirm → a `.json` downloads. This file is a secret.
 4. **Human tells you the file path** to the downloaded JSON.
 5. **You (agent):** confirm the JSON is gitignored / outside the repo, ask the consent question ([The API-upload mechanism](#the-api-upload-mechanism-shared-by-apple-p8-and-firebase)), then upload: the MCP tool with the Base64 string as **`fcm_v1_service_account_json`** (the only required Android param per the reference page), or `onesignal_api.py provision <APP_ID> --fcm-json <path>` on the direct path. Validate the response.
-6. **`google-services.json` is NOT a OneSignal credential.** OneSignal authenticates to FCM entirely server-side with the service-account JSON. Do not ask for `google-services.json` and do not upload it. It is only relevant if the app *itself* uses Firebase client SDKs — that's the app's own concern, not OneSignal's. (The upstream ai-prompt that requires it is a known bug; see platform-matrix Android notes.)
+6. **`google-services.json` is not a OneSignal credential.** OneSignal authenticates to FCM entirely server-side with the service-account JSON. Never ask the user to upload `google-services.json` to OneSignal, and never upload it yourself. It is Firebase *client* configuration that ships inside the app — recommended on Android SDK 5.11.0+, and set up in the **setup** skill, not here. Both files must come from the same Firebase project; a mismatch produces subscription status `-6`. See platform-matrix Android notes.
 
 ## Credential validation loop
 
diff --git a/skills/credentials/api-uploaded-credentials.md b/skills/credentials/api-uploaded-credentials.md
index b964663..07e2806 100644
--- a/skills/credentials/api-uploaded-credentials.md
+++ b/skills/credentials/api-uploaded-credentials.md
@@ -92,7 +92,7 @@ OneSignal authenticates to FCM entirely server-side using the service-account JS
 - Do not upload it.
 - It only matters if the app *itself* embeds Firebase client SDKs (Analytics, Firestore, etc.) — that's the app's own setup, unrelated to OneSignal push.
 
-The upstream OneSignal ai-install-prompt that asks for `google-services.json` is a **known bug** (see [../../references/platform-matrix.md](../../references/platform-matrix.md) Android notes). Follow this file, not that prompt.
+`google-services.json` is never uploaded to OneSignal — it is client configuration handled by the **setup** skill, not a credential (see [../../references/platform-matrix.md](../../references/platform-matrix.md) Android notes). It must come from the same Firebase project as the service account uploaded here, or Android subscriptions show status `-6`.
 
 ### FCM failure modes → what to tell the user (surface the raw error first)
 | Symptom | Likely cause | Fix |
diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md
index 4bc5b92..fc1255d 100644
--- a/skills/setup/SKILL.md
+++ b/skills/setup/SKILL.md
@@ -340,7 +340,7 @@ Decide what is still missing:
 
 Emit a copy-ready summary: files changed; SDK version + that it came from the releases.json endpoint; the dashboard/console steps the human still owns (from the platform's "Human must do" column in the matrix); verification steps (run the debug build → accept the permission prompt → the verify skill confirms the subscription and sends the test push); the verification helper's filename + call site (debug-only; safe to keep, deletable on request); and rollback commands (`git checkout -- <files>` / delete the `onesignal-integration` branch / restore `.onesignal.bak` files). **Do NOT auto-commit or open a PR** — offer the commands; the user runs them.
 
-Before finishing, **run the structural self-check and fix anything it flags** — do not rely on the build or on your own reading: `python3 <plugin>/scripts/verify_integration.py <project_dir> --platform <platform> --app-id <APP_ID>`. It deterministically verifies the constraint-following facts a compiler cannot see (exact version pin, no placeholder/fabricated App ID, init in an Application subclass, the verification file guarded by `BuildConfig.DEBUG` so it can't ship to release, `onesignal:managed` markers, no stray `google-services.json`, no deprecated `addOutcome`). If `verdict` is `fail`, repair each error-level check and re-run until it passes; only then declare done. This is the deterministic close of the loop — the agent catches its own slips (e.g. a verification file that names `installIfDebug` but forgets the guard) instead of shipping them. If the script cannot run because Python is missing (Step 0.2), check each item in that list by reading the files you wrote, and say in the summary that the structural self-check did not run.
+Before finishing, **run the structural self-check and fix anything it flags** — do not rely on the build or on your own reading: `python3 <plugin>/scripts/verify_integration.py <project_dir> --platform <platform> --app-id <APP_ID>`. It deterministically verifies the constraint-following facts a compiler cannot see (exact version pin, no placeholder/fabricated App ID, init in an Application subclass, the verification file guarded by `BuildConfig.DEBUG` so it can't ship to release, `onesignal:managed` markers, the Google Services plugin never applied without a `google-services.json` to process, no deprecated `addOutcome`). If `verdict` is `fail`, repair each error-level check and re-run until it passes; only then declare done. This is the deterministic close of the loop — the agent catches its own slips (e.g. a verification file that names `installIfDebug` but forgets the guard) instead of shipping them. If the script cannot run because Python is missing (Step 0.2), check each item in that list by reading the files you wrote, and say in the summary that the structural self-check did not run.
 
 Before finishing, **scan your own diff for secret-shaped strings** deterministically: `python3 <plugin>/scripts/scan_secrets.py` (scans the working-tree diff; add `--staged` for staged changes, or pass file paths). It flags REST/org keys, `.p8`/service-account contents, and `Authorization: Key` headers while ignoring the public App ID and obvious placeholders, and never prints the matched value — only its file, line, column, and rule. If it exits non-zero, abort and remove the secret — keys live in env vars only (safety contract §"Never"). If the script cannot run because Python is missing (Step 0.2), read `git diff` yourself and look for the same shapes: long key-like strings, `Authorization: Key` headers, `-----BEGIN PRIVATE KEY-----`, and `"private_key"` JSON fields. If you find one, the rule is the same as the scripted path: abort, remove the secret, and do not declare done until the diff is clean.
 
diff --git a/skills/setup/android.md b/skills/setup/android.md
index 86c04ab..f4a6b0a 100644
--- a/skills/setup/android.md
+++ b/skills/setup/android.md
@@ -2,9 +2,18 @@
 
 Reference for the `setup` skill. Follow [SKILL.md](SKILL.md) Steps 0–8; this file is the Android install detail. `<plugin>` in the commands below is the directory SKILL.md defines: walk up from this file's directory to the first directory that contains a `scripts/` folder. Mirrors the proven flow in `sdk-ai-prompts/docs/android/integrate.md` with ONE correction from the matrix (below). Do not contradict [../../references/platform-matrix.md](../../references/platform-matrix.md).
 
-## google-services.json is NOT required (matrix correction)
+## google-services.json: not required, but recommended
 
-The upstream Android prompt tells you to add `google-services.json` + the Google Services Gradle plugin. **That is a known bug.** OneSignal delivers push via server-side **FCM v1 credentials** (a service-account JSON the human uploads to the OneSignal app, handled by the **credentials** skill). Do NOT add `google-services.json`, the `com.google.gms:google-services` classpath, or `apply plugin: 'com.google.gms.google-services'` — **unless the app itself already uses Firebase client SDKs** (grep for `com.google.firebase` deps / an existing `google-services.json`). If it does, leave the existing Firebase setup alone; still don't add it for OneSignal's sake.
+Push delivery does not depend on it. OneSignal sends via server-side **FCM v1 credentials** (a service-account JSON the human uploads to the OneSignal app, handled by the **credentials** skill), so the integration works without `google-services.json`.
+
+It is nonetheless **recommended for new integrations**. On OneSignal Android SDK **5.11.0+**, when the app has its own default `FirebaseApp`, push registers through the customer's Firebase project instead of OneSignal's shared one.
+
+**Agent behavior:**
+
+- Do NOT add or remove `google-services.json`, and do NOT add the `com.google.gms:google-services` classpath or `apply plugin:` line on your own. You cannot produce the file — it comes from the customer's Firebase console — and applying the plugin without the file fails the build with `File google-services.json is missing`.
+- If the app already has the file and the plugin, leave both in place.
+- If it has neither, continue. Tell the user that adding their own `google-services.json` plus the plugin is recommended, and that they download it from their Firebase console. See [Android Firebase credentials](https://documentation.onesignal.com/docs/en/android-firebase-credentials#add-your-firebase-configuration-file).
+- If `firebase_messaging_installation_id_enabled` is `true` in the **merged** manifest — a dependency such as Braze 43.0.0+ can set it through manifest merging — then `google-services.json`, the Gradle plugin, and `firebase-messaging` 25.1.2+ are **required**. Stop and tell the user; without them, push registration fails with subscription status `-32`. See [Firebase Installation ID registration](https://documentation.onesignal.com/docs/en/android-firebase-installation-id).
 
 `POST_NOTIFICATIONS` (Android 13+) is manifest-merged by the SDK — do not add it. Only `INTERNET` needs to be present (it usually already is).
 
diff --git a/skills/setup/cross-platform.md b/skills/setup/cross-platform.md
index 0b3811d..7ebde4c 100644
--- a/skills/setup/cross-platform.md
+++ b/skills/setup/cross-platform.md
@@ -17,7 +17,7 @@ Detected by `react-native` in `package.json` WITHOUT `expo`. Ask JS vs TS (upstr
   OneSignal.initialize('YOUR_ONESIGNAL_APP_ID'); // onesignal:managed v1
   ```
 - **iOS side is manual native work** (Xcode): Push + Background Modes capabilities, and NSE + App Group only if rich media/confirmed delivery are wanted (App Group is required if an NSE is added). Guide the human — these are GUI/pbxproj steps (see ios.md).
-- **Android side is handled by the plugin** — no manual Gradle/manifest edits documented (matrix). Do NOT add `google-services.json` (the FCM v1 credential is server-side; see android.md).
+- **Android side is handled by the plugin** — no manual Gradle/manifest edits documented (matrix). Do not add `google-services.json` yourself; it is recommended but the user supplies it (see android.md).
 - Environment prerequisites (upstream, critical): Android needs **JDK 17** (JDK 25+ breaks CMake); RN 0.71+ (0.76+ recommended); New Architecture needs RN 0.79+. State constraints; don't silently upgrade the project.
 
 ## Flutter (`onesignal_flutter`)
@@ -37,7 +37,7 @@ Detected by `pubspec.yaml`. Full detail: `sdk-ai-prompts/docs/flutter/integrate.
   ```
 - Wrapper: a single `OneSignalService` class (async methods). Signatures per api-reference "SDK data surface"; tag values are strings; `login()` before tags/email/sms.
 - Verification helper (debug-only): guard the whole thing on `kDebugMode` (from `package:flutter/foundation.dart`); register `OneSignal.User.pushSubscription.addObserver((state) {...})` reading `state.current.id`, and read `OneSignal.User.pushSubscription.id` immediately (race guard); `await OneSignal.Notifications.requestPermission(false)` returns `Future<bool>` (like web/RN — NOT iOS's completion block or Android's suspend form; keep `fallbackToSettings` `false` for a launch-time call with no user gesture). A notification-received listener is not proof of registration — key off the push subscription. The Step-8 self-check (`verify_integration.py --platform flutter`) enforces init in `main()`, the `kDebugMode` guard, and the real push-subscription observer.
-- iOS side: same native Xcode human steps as ios.md (Flutter's `ios/` subproject). Android side: the plugin handles Gradle/manifest; do NOT add `google-services.json`. Flutter 3.29+ recommended (matrix).
+- iOS side: same native Xcode human steps as ios.md (Flutter's `ios/` subproject). Android side: the plugin handles Gradle/manifest; do not add `google-services.json` yourself (see android.md). Flutter 3.29+ recommended (matrix).
 
 ## Cordova (`onesignal-cordova-plugin`)
 
@@ -51,7 +51,7 @@ Detected by `config.xml` + `cordova` in `package.json`.
   ```
   Verify the exact JS namespace (`window.plugins.OneSignal` vs an imported module) against the current Cordova SDK reference before finalizing — API surface is authoritative.
 - `OneSignal.Notifications.requestPermission(fallbackToSettings?)` returns `Promise<boolean>`; read the subscription id with `OneSignal.User.pushSubscription.getIdAsync()` (the `.id` getter is deprecated) and observe with `pushSubscription.addEventListener('change', (e) => e.current.id)`. The Step-8 self-check (`verify_integration.py --platform cordova`) enforces the package present, init present (near `deviceready`), and that the verification file reads the push subscription (not a notification-received listener).
-- Native iOS/Android obligations are the same as the RN wrapper: iOS GUI capabilities (+ NSE for rich features), no `google-services.json` for Android.
+- Native iOS/Android obligations are the same as the RN wrapper: iOS GUI capabilities (+ NSE for rich features); do not add `google-services.json` yourself for Android.
 
 ## Capacitor / Ionic (`@onesignal/capacitor-plugin`)
 
@@ -68,7 +68,7 @@ Detected by `capacitor.config.{ts,js,json}` or `@capacitor/core` in `package.jso
   OneSignal.initialize('YOUR_ONESIGNAL_APP_ID'); // onesignal:managed v1
   ```
 - `OneSignal.initialize(appId)` returns `Promise<void>`; `requestPermission(fallbackToSettings?)` returns `Promise<boolean>`; read the id with `pushSubscription.getIdAsync()` and observe with `pushSubscription.addEventListener('change', ...)`. The Step-8 self-check (`verify_integration.py --platform capacitor`) enforces the package present, init present, `ios.handleApplicationNotifications=false`, and that the verification file reads the push subscription.
-- Native obligations same as above (iOS GUI; Android handled by plugin, no `google-services.json`). Run `npx cap sync` after native config changes.
+- Native obligations same as above (iOS GUI; Android handled by plugin; do not add `google-services.json` yourself). Run `npx cap sync` after native config changes.
 
 ## Unity (`OneSignal.Initialize`)
 
diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md
index 0ec9f3d..0d1ad25 100644
--- a/skills/verify/SKILL.md
+++ b/skills/verify/SKILL.md
@@ -204,7 +204,7 @@ Diagnose in this ranked order — grounded in the real OneSignal failure modes.
 1. **Installed but nothing ever registers / nothing delivers (step 2 timeout or `errored`>0)** → **missing platform credentials** (no FCM service-account JSON for Android, no APNs .p8/.p12 for iOS, no web platform config). This is the #1 cause. **Check the opt-in state before this diagnosis:** a step-2 row with `notification_types < 1` means the permission tap never happened → §5, not credentials. And on iOS v5 the subscription row appears without platform credentials (the create-user path), so a missing `.p8` usually surfaces as `errored` at rung 5, not as a step-2 timeout. On an iOS integration without the `remote-notification` background mode (setup did not write it), a step-2 timeout usually means the prompt was never accepted → §5. → route to the **credentials skill**.
 2. **Web: platform never provisioned, or service worker 404/403, wrong MIME type, redirect, or scope conflict** → FIRST check the sync probe: `App not configured for web push` / `{"code":2}` means the dashboard web-platform step never happened (signup doesn't do it) — fix there, and remember the error is CDN-cached ~1 h. Otherwise: `OneSignalSDKWorker.js` must be same-origin, served as `application/javascript`, no redirect, at the configured path; Site URL in the dashboard must EXACTLY match the origin (protocol + domain + subdomain).
 3. **iOS: no subscription** → needs a physical device or Apple-silicon-Mac simulator (Intel-Mac simulators won't register for remote push); Push capability + provisioning (without them the token fetch itself fails — APNS 3000). A missing APNs `.p8` shows as `errored` at rung 5, not here (platform-verification.md §3).
-4. **Android: no subscription** → FCM v1 service-account JSON uploaded; test device has **Google Play Services** (emulator must be a Play-services image). Note `google-services.json` is NOT required for OneSignal push.
+4. **Android: no subscription** → FCM v1 service-account JSON uploaded; test device has **Google Play Services** (emulator must be a Play-services image). Note `google-services.json` is not required for OneSignal push, though it is recommended on SDK 5.11.0+. If subscriptions show `-32`, `-33` or `-34`, see [Firebase Installation ID registration](https://documentation.onesignal.com/docs/en/android-firebase-installation-id).
 5. **Permission not granted** → the OS/browser prompt was dismissed or blocked; `requestPermission` / opt-in never ran, or `optOut()` is being called.
 6. **"Delivered" (`successful>=1`) but not shown** → Focus/DND or device notification settings, another push SDK (Firebase Messaging) intercepting, foreground `preventDefault()`, app force-closed/offline — or several rapid test sends collapsing so only the last displays (check each message's `successful` count before calling it a failure). On an emulator that the host may have suspended, cold-boot the device — an app relaunch does not restore a stale FCM transport. 1 resend maximum; full detail and the checkpoint to report are in platform-verification.md §6.
 
diff --git a/skills/verify/platform-verification.md b/skills/verify/platform-verification.md
index a121bd3..3e3f5fe 100644
--- a/skills/verify/platform-verification.md
+++ b/skills/verify/platform-verification.md
@@ -99,7 +99,7 @@ Diagnose in this ranked order. For each: symptom → most-likely cause → fix /
 **Causes & fixes:**
 - **FCM v1 credentials missing** → credentials skill (see §1).
 - **No Google Play Services** on the test device/emulator → use a Play-services emulator image or a real device.
-- **`google-services.json` confusion:** it is **NOT required** for OneSignal push (FCM v1 creds are server-side). Only keep it if the app itself uses Firebase client SDKs. Do not tell the user to add it for OneSignal.
+- **`google-services.json`:** not **required** for OneSignal push (FCM v1 creds are server-side), but **recommended** on SDK 5.11.0+, and required when `firebase_messaging_installation_id_enabled` is `true` in the merged manifest. Never remove one the app already has.
 - **`ActivityNotFoundException` for `PermissionsActivity`:** open the app `AndroidManifest.xml`. If `<application>` has `tools:node="replace"`, warn the user: that drops all OneSignal manifest components (for example `PermissionsActivity`). The notification permission flow crashes and push registration also breaks. Remove `tools:node="replace"`. Override one attribute with `tools:replace` instead. Confirm `com.onesignal.core.activities.PermissionsActivity` is in `app/build/intermediates/merged_manifests`.
 
 ### 5. Permission not granted