From 5bfd4d7e89cce0823aaea93e6dfd377b4b1101aa Mon Sep 17 00:00:00 2001
From: sherwinski <sherwin@onesignal.com>
Date: Thu, 22 Oct 2026 17:55:37 -0700
Subject: [PATCH 1/6] chore: exempt fenced code blocks from the parent-path
 gate

A pbxproj snippet in a skill carries an rpath with ../../ in it. That
text goes into the user's project and is not a link the plugin resolves,
so the gate now skips fenced code blocks for the parent-segment check
only. A new self-test case keeps a ../ in prose rejected.
---
 AGENT.md                            |  4 +++-
 scripts/package_directory_bundle.py | 32 +++++++++++++++++++++++++++--
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/AGENT.md b/AGENT.md
index a49698e..427bd6a 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -87,7 +87,9 @@ Do not break these without a decision from the team:
   single call; a compound command prompts.
 - **Shared files have one spelling in skill text.** A skill refers to a shared script only as
   `<plugin>/scripts/<name>`, and to a reference only as `[…](../../references/<name>.md)`.
-  No other path in a skill may contain `../`. `scripts/package_directory_bundle.py --check`
+  No other path in a skill may contain `../`; a fenced code block is exempt, because its
+  content goes into the user's project (a pbxproj `rpath`, for example) and is not a link
+  the plugin resolves. `scripts/package_directory_bundle.py --check`
   enforces this convention, and any other spelling fails the check. The convention is what
   lets the packager build the self-contained bundle with one rewrite (see "The OpenAI
   directory bundle" below).
diff --git a/scripts/package_directory_bundle.py b/scripts/package_directory_bundle.py
index c660856..6b89d14 100755
--- a/scripts/package_directory_bundle.py
+++ b/scripts/package_directory_bundle.py
@@ -212,6 +212,25 @@ def allowed_tools_lines(text):
     return numbers
 
 
+def fenced_code_lines(text):
+    """Return the 1-based line numbers inside fenced code blocks.
+
+    Only the parent-segment check skips these lines: a `../` inside a fence is
+    content the agent writes into the user's project (a pbxproj `rpath`, for
+    example), not a link the plugin resolves. Every other check still reads
+    fenced lines, because the `<plugin>/scripts/` calls live in them.
+    """
+    numbers = set()
+    in_fence = False
+    for lineno, line in enumerate(text.splitlines(), 1):
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            numbers.add(lineno)
+    return numbers
+
+
 # ---------------------------------------------------------------------------
 # Version
 # ---------------------------------------------------------------------------
@@ -357,12 +376,13 @@ def check_source(source):
             rel = relpath(path, source)
             text = read_text(path)
             allowed_tools = allowed_tools_lines(text) if path == skill_md else set()
+            fenced = fenced_code_lines(text)
             for lineno, line in enumerate(text.splitlines(), 1):
                 if BARE_SCRIPT_RE.search(line) and lineno not in allowed_tools:
                     findings.append("%s:%d: script path without the <plugin>/ prefix" % (rel, lineno))
                 if BARE_REFERENCE_RE.search(line):
                     findings.append("%s:%d: reference path without the ../../ prefix" % (rel, lineno))
-                if PARENT_SEGMENT_RE.search(line.replace("../../references/", "")):
+                if lineno not in fenced and PARENT_SEGMENT_RE.search(line.replace("../../references/", "")):
                     findings.append("%s:%d: relative path leaves the skill folder (only ../../references/ is allowed)" % (rel, lineno))
                 if HOST_PATH_RE.search(line) and lineno not in allowed_tools:
                     findings.append("%s:%d: host-specific path or environment variable" % (rel, lineno))
@@ -498,8 +518,9 @@ def check_bundle(bundle_dir):
             in_references = relpath(path, skill_dir).startswith("references/")
             text = read_text(path)
             allowed_tools = allowed_tools_lines(text) if path == skill_md else set()
+            fenced = fenced_code_lines(text)
             for lineno, line in enumerate(text.splitlines(), 1):
-                if PARENT_SEGMENT_RE.search(line):
+                if lineno not in fenced and PARENT_SEGMENT_RE.search(line):
                     findings.append("%s:%d: a relative path still leaves the skill folder" % (rel, lineno))
                 if HOST_PATH_RE.search(line) and lineno not in allowed_tools:
                     findings.append("%s:%d: host-specific path or environment variable" % (rel, lineno))
@@ -648,6 +669,13 @@ def self_test(source):
         ok = expect_failure("reference link with a single ../", bad, os.path.join(tmp, "bad-reference-link-work"),
                             "reference path without the ../../ prefix") and ok
 
+        bad = os.path.join(tmp, "bad-parent-path-in-prose")
+        copy_source_subset(source, bad)
+        with open(os.path.join(bad, "skills", "setup", "SKILL.md"), "a", encoding="utf-8") as handle:
+            handle.write("\nCopy the file from ../shared/template.swift.\n")
+        ok = expect_failure("a ../ path in prose outside a code fence", bad, os.path.join(tmp, "bad-parent-path-in-prose-work"),
+                            "relative path leaves the skill folder") and ok
+
         bad = os.path.join(tmp, "bad-missing-reference")
         copy_source_subset(source, bad)
         with open(os.path.join(bad, "skills", "credentials", "SKILL.md"), "a", encoding="utf-8") as handle:

From da8aea4a21c82c2712dc9fc284054f0e0272613a Mon Sep 17 00:00:00 2001
From: sherwinski <sherwin@onesignal.com>
Date: Thu, 22 Oct 2026 17:55:37 -0700
Subject: [PATCH 2/6] feat: install the iOS SDK from OneSignal-XCFramework with
 the NSE and App Group

The resolver's SPM line now names the OneSignal-XCFramework package and
the product-to-target map; the Podfile output gains the in-app messages
subspec and a line for the extension target. The default product set is
OneSignalFramework and OneSignalInAppMessages on the app target and
OneSignalExtension on the extension; OneSignalLocation is added only on
request.

The Notification Service Extension and the App Group are now part of the
default native iOS install. ios-nse.md holds the recipe, 3 new templates
hold the extension files, compile_check_ios.sh compiles the Swift one
against a stub of OneSignalExtension.h, and verify_integration.py checks
the target, the link, and the shared App Group. The safety and telemetry
contracts, the platform matrix, and the prior-install detection follow.
---
 references/platform-matrix.md                 |   2 +-
 references/safety-contract.md                 |   4 +-
 references/telemetry-contract.md              |  13 +-
 scripts/compile_check_ios.sh                  |  46 +++-
 scripts/detect_platform.py                    |   2 +-
 scripts/resolve_sdk_version.py                |  19 +-
 scripts/verify_integration.py                 |  56 ++++-
 skills/setup/SKILL.md                         |   2 +-
 .../assets/ios/NotificationService.swift.tmpl |  43 ++++
 ...tificationServiceExtension-Info.plist.tmpl |  31 +++
 ...ficationServiceExtension.entitlements.tmpl |  10 +
 skills/setup/ios-nse.md                       | 237 ++++++++++++++++++
 skills/setup/ios.md                           |  63 +++--
 skills/verify/platform-verification.md        |   2 +-
 14 files changed, 494 insertions(+), 36 deletions(-)
 create mode 100644 skills/setup/assets/ios/NotificationService.swift.tmpl
 create mode 100644 skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl
 create mode 100644 skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl
 create mode 100644 skills/setup/ios-nse.md

diff --git a/references/platform-matrix.md b/references/platform-matrix.md
index 59adc92..f1a0a80 100644
--- a/references/platform-matrix.md
+++ b/references/platform-matrix.md
@@ -9,7 +9,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. |
-| **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. |
+| **iOS native** | SPM (`OneSignal-XCFramework` repo — never `OneSignal-iOS-SDK`; `OneSignalFramework` + `OneSignalInAppMessages`→app, `OneSignalExtension`→NSE) or Podfile (`OneSignal/OneSignal` + `OneSignal/OneSignalInAppMessages` on the app target, `OneSignal/OneSignal` on the NSE target); `OneSignal.initialize(appId, withLaunchOptions:)` in AppDelegate/adaptor; Info.plist `UIBackgroundModes remote-notification`; entitlements text (`aps-environment` + App Group); the NSE folder (3 templates) and its pbxproj target objects; 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) only when the pbxproj format does not match the recipe; physical-device test (launch from Xcode) + the notification permission tap | NSE + App Group are part of the default install (images, badges, confirmed receipt fail silently without them); `OneSignalLocation` only on request. 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/references/safety-contract.md b/references/safety-contract.md
index 8ee8432..7736c87 100644
--- a/references/safety-contract.md
+++ b/references/safety-contract.md
@@ -7,14 +7,14 @@ Any skill that reads or writes the user's repository MUST follow all of this. It
 1. `git status --porcelain -- ":(exclude,top).onesignal"` — if the tree is dirty, STOP and ask (stash / proceed / abort). `.onesignal/` is run state (§20), never project content, so it never makes the tree dirty: the `top` pathspec excludes it at the repo root from any working directory, whether it is untracked or modified. No `.git`? Fall back to `.onesignal.bak` sibling backups and say there's no VCS net.
 2. Detect prior installation FIRST: existing OneSignal dependency line, existing init call, or our marker comment. Found → propose update/repair, never a duplicate. Different App ID already present → ask which is correct; never silently overwrite.
 3. Default to a new `onesignal-integration` branch (user may opt into current branch).
-4. Declare the complete file allow-list up front (dependency manifest, init/lifecycle file, one wrapper module, platform config files, one debug-only verification helper, `.gitignore`, web service-worker, `.onesignal/` checkpoint run state). Touching anything else requires re-confirmation.
+4. Declare the complete file allow-list up front (dependency manifest, init/lifecycle file, one wrapper module, platform config files, the iOS Notification Service Extension folder, one debug-only verification helper, `.gitignore`, web service-worker, `.onesignal/` checkpoint run state). Touching anything else requires re-confirmation.
 
 ## Writing
 
 5. Compute the FULL change set and show it as diffs BEFORE any write. One confirmation for the whole set. Apply exactly as previewed; if a file drifted, abort that file and re-preview.
 6. Mark generated blocks: `// onesignal:managed v1` — idempotency keys off this marker on re-runs.
 7. Match the repo's style, package manager (detect via lockfile), and architecture. No repo-wide reformatting, no unrelated dep bumps, no import reordering.
-8. Minimal integration only: init + permission in the right lifecycle spot. No extra OneSignal features unless asked.
+8. Minimal integration only: init + permission in the right lifecycle spot. No extra OneSignal features unless asked. On native iOS the minimal integration includes the Notification Service Extension, the App Group, and the `OneSignalInAppMessages` product: without the first two, images, badges, and confirmed delivery fail silently, and the third is the documented default with no code of its own. `OneSignalLocation` is an extra feature.
 
 ## Never
 
diff --git a/references/telemetry-contract.md b/references/telemetry-contract.md
index 0d233ee..dd9fcab 100644
--- a/references/telemetry-contract.md
+++ b/references/telemetry-contract.md
@@ -72,10 +72,12 @@ Each is `skill.milestone`. Status is `ok`, `ok_after_fix`, or `fail`.
 `platform` field separates them. It fires once the Step-5 change set and the Step-6
 verification helper both exist, because the prerequisites span both steps:
 
-- `ios` — the capability set and the permission request: `UIBackgroundModes`
+- `ios` — the capability set, the permission request, and the extension: `UIBackgroundModes`
   `remote-notification`, the `aps-environment` entitlement, the pbxproj build settings,
-  and the `requestPermission` call in the verification helper. When the pbxproj format
-  does not match and the capability toggle goes to the human in Xcode, report
+  the `requestPermission` call in the verification helper, the
+  `OneSignalNotificationServiceExtension` target with `OneSignalExtension` linked, and the
+  same App Group in both entitlements files. When the pbxproj format does not match and
+  the capability toggle or the NSE target creation goes to the human in Xcode, report
   `fail capability_manual` at the hand-off and continue. Like `deferred` on the
   credentials gate, this records a drop out of agent automation, not a skill stop.
 - `android` — the permission state: `INTERNET` present in the manifest, no manual
@@ -195,8 +197,9 @@ this; android.md documents the exact dependency line). Sibling of `buildconfig_d
 correct code that does not compile until the app module declares one more thing.
 
 `capability_manual`: the iOS pbxproj edits could not apply safely, so the Push
-Notifications and Background Modes toggles went to the human in Xcode. The run cannot
-observe when the human completes them, so the milestone records the hand-off itself.
+Notifications and Background Modes toggles, or the creation of the Notification Service
+Extension target, went to the human in Xcode. The run cannot observe when the human
+completes them, so the milestone records the hand-off itself.
 
 `worker_scope_conflict`: the site already registers a service worker at the scope
 OneSignal needs. `setup.platform_config` reports the resolved conflict — the combine or
diff --git a/scripts/compile_check_ios.sh b/scripts/compile_check_ios.sh
index 4b95cd1..7e9fad6 100755
--- a/scripts/compile_check_ios.sh
+++ b/scripts/compile_check_ios.sh
@@ -67,12 +67,34 @@ public enum OneSignal {
 }
 SW
 
+# --- Faithful OneSignalExtension stub (validated against OneSignalExtension.h) ---
+# The header has no nullability region, so Swift imports the ObjC class methods
+# with optional parameters and an optional return; the return is discardable.
+cat > "$WORK/OneSignalExtension.swift" <<'SW'
+import Foundation
+import UserNotifications
+public class OneSignalExtension: NSObject {
+    @discardableResult
+    public class func didReceiveNotificationExtensionRequest(
+        _ request: UNNotificationRequest, with replacementContent: UNMutableNotificationContent?,
+        withContentHandler contentHandler: ((UNNotificationContent) -> Void)?
+    ) -> UNMutableNotificationContent? { nil }
+    @discardableResult
+    public class func serviceExtensionTimeWillExpireRequest(
+        _ request: UNNotificationRequest, with replacementContent: UNMutableNotificationContent?
+    ) -> UNMutableNotificationContent? { nil }
+}
+SW
+
 sc() { xcrun --sdk iphonesimulator swiftc -target "$TARGET" "$@"; }
 
-echo "building OneSignal stub module..."
+echo "building OneSignal stub modules..."
 sc -emit-module -module-name OneSignalFramework \
    -emit-module-path "$WORK/out/OneSignalFramework.swiftmodule" \
    -parse-as-library "$WORK/OneSignalFramework.swift"
+sc -emit-module -module-name OneSignalExtension \
+   -emit-module-path "$WORK/out/OneSignalExtension.swiftmodule" \
+   -parse-as-library "$WORK/OneSignalExtension.swift"
 
 fail=0
 
@@ -90,6 +112,19 @@ if sc -typecheck -I "$WORK/out" "$WORK/manager.swift"; then
 else
     echo "✗ OneSignalManager.swift.tmpl FAILED to compile"; fail=1
 fi
+cp "$ASSETS/NotificationService.swift.tmpl" "$WORK/nse.swift"
+if sc -typecheck -I "$WORK/out" "$WORK/nse.swift"; then
+    echo "✓ NotificationService.swift.tmpl compiles"
+else
+    echo "✗ NotificationService.swift.tmpl FAILED to compile"; fail=1
+fi
+for plist in OneSignalNotificationServiceExtension-Info.plist.tmpl OneSignalNotificationServiceExtension.entitlements.tmpl; do
+    if sed 's/__MAIN_APP_BUNDLE_ID__/com.example.app/' "$ASSETS/$plist" | plutil -lint - >/dev/null; then
+        echo "✓ $plist is a valid plist"
+    else
+        echo "✗ $plist is NOT a valid plist"; fail=1
+    fi
+done
 
 # --- negative controls: fabricated call shapes MUST NOT compile ---
 cat > "$WORK/bad_web.swift" <<'SW'
@@ -100,7 +135,14 @@ cat > "$WORK/bad_suspend.swift" <<'SW'
 import OneSignalFramework
 func x() async { _ = await OneSignal.Notifications.requestPermission(true) }
 SW
-for bad in bad_web bad_suspend; do
+cat > "$WORK/bad_nse_label.swift" <<'SW'
+import UserNotifications
+import OneSignalExtension
+func x(_ r: UNNotificationRequest, _ c: UNMutableNotificationContent, _ h: @escaping (UNNotificationContent) -> Void) {
+    OneSignalExtension.didReceiveNotificationExtensionRequest(r, withMutableNotificationContent: c, withContentHandler: h)
+}
+SW
+for bad in bad_web bad_suspend bad_nse_label; do
     if sc -typecheck -I "$WORK/out" "$WORK/$bad.swift" 2>/dev/null; then
         echo "✗ negative control $bad UNEXPECTEDLY compiled — stub is a rubber stamp"; fail=1
     else
diff --git a/scripts/detect_platform.py b/scripts/detect_platform.py
index 6556e4b..5d98f19 100755
--- a/scripts/detect_platform.py
+++ b/scripts/detect_platform.py
@@ -223,7 +223,7 @@ def find_packages(root):
     (r"onesignal_flutter", "flutter package"),
     (r"onesignal-cordova-plugin", "cordova plugin"),
     (r"@onesignal/capacitor-plugin", "capacitor plugin"),
-    (r"OneSignalXCFramework|OneSignal-iOS-SDK", "iOS SDK"),
+    (r"OneSignal-?XCFramework|OneSignal-iOS-SDK|pod\s+['\"]OneSignal", "iOS SDK"),
     (r"OneSignal\.(init|initialize|initWithContext)", "init call"),
     (r"onesignal:managed", "managed marker"),
     (r"OneSignalSDKWorker", "web service worker"),
diff --git a/scripts/resolve_sdk_version.py b/scripts/resolve_sdk_version.py
index 30386c2..f5618fc 100755
--- a/scripts/resolve_sdk_version.py
+++ b/scripts/resolve_sdk_version.py
@@ -43,14 +43,25 @@
         },
         "default_line": "gradle-kts",
     },
+    # The feed entry is the OneSignal-iOS-SDK repository. The SPM package lives in
+    # OneSignal-XCFramework, which publishes the same version tags, so the pin
+    # applies to both. The app target takes OneSignalFramework and
+    # OneSignalInAppMessages; the Notification Service Extension target takes
+    # OneSignalExtension; OneSignalLocation is added only on request.
     "ios": {
         "feed": "iOS",
-        "coordinate": "OneSignal-iOS-SDK / OneSignalXCFramework",
+        "coordinate": "OneSignal-XCFramework (SPM) / OneSignal (CocoaPods)",
         "lines": {
-            "spm": 'https://github.com/OneSignal/OneSignal-iOS-SDK — "Exact Version" {v} (product: OneSignalFramework)',
-            "podfile": "pod 'OneSignal/OneSignal', '{v}' # onesignal:managed v1",
+            "spm": 'https://github.com/OneSignal/OneSignal-XCFramework — "Exact Version" {v}; '
+                   'app target: OneSignalFramework, OneSignalInAppMessages; '
+                   'OneSignalNotificationServiceExtension target: OneSignalExtension',
+            "podfile": "pod 'OneSignal/OneSignal', '{v}' # onesignal:managed v1\n"
+                       "pod 'OneSignal/OneSignalInAppMessages', '{v}' # onesignal:managed v1",
+            "podfile-nse": "pod 'OneSignal/OneSignal', '{v}' # onesignal:managed v1",
         },
         "default_line": "spm",
+        "note": "The feed lists OneSignal-iOS-SDK; OneSignal-XCFramework publishes the same "
+                "version tags, so this pin is the SPM package version too.",
     },
     "react-native": {
         "feed": "ReactNative",
@@ -215,6 +226,8 @@ def main():
             f"Web pins to the fixed CDN major {spec['web_fixed_major']}; "
             f"feed build number is {version} (metadata only)."
         )
+    if spec.get("note"):
+        out["note"] = spec["note"]
     if track_used != args.track:
         fallback = f"Requested track '{args.track}' had no release; used '{track_used}'."
         out["note"] = (out.get("note", "") + " " + fallback).strip()
diff --git a/scripts/verify_integration.py b/scripts/verify_integration.py
index 280c16f..9a28f28 100755
--- a/scripts/verify_integration.py
+++ b/scripts/verify_integration.py
@@ -24,9 +24,11 @@
 EXCLUDE = {"node_modules", "build", ".gradle", "Pods", ".git", "dist", "DerivedData",
            "__pycache__", ".dart_tool", "out"}
 CODE_EXTS = {".kt", ".java", ".swift", ".m", ".ts", ".tsx", ".js", ".jsx", ".dart",
-             ".gradle", ".kts", ".html", ".xml", ".rb", ".ruby", ".plist", ".json", ".toml"}
+             ".gradle", ".kts", ".html", ".xml", ".rb", ".ruby", ".plist", ".json", ".toml",
+             ".entitlements"}
 # .toml is needed for gradle/libs.versions.toml (version-catalog dependency decls).
 # .json is needed for package.json / app.json (Expo/RN config, npm version ranges).
+# .entitlements is needed for the iOS App Group check (plist XML).
 
 # A OneSignal dependency line carrying a range/dynamic version instead of a pin.
 RANGE_PATTERNS = [
@@ -385,6 +387,55 @@ def ios_verification_uses_push_observer(self):
                       + (" and relies on NotificationCenter (a OneSignal registration event it never posts — dead)" if uses_notifcenter else ""))
         self.add("ios_verification_uses_push_observer", ok, "error", detail)
 
+    def ios_nse_present(self):
+        # The Notification Service Extension is part of the default native install
+        # (ios.md): without it, images, badges, and confirmed delivery fail silently
+        # while plain pushes still arrive, so nothing else in this check catches it.
+        manifests = [fp for fp in walk_files(self.root)
+                     if os.path.basename(fp) in ("project.pbxproj", "Podfile")]
+        blob = "\n".join(read(fp) for fp in manifests)
+        target = "OneSignalNotificationServiceExtension" in blob
+        linked = re.search(r"productName\s*=\s*OneSignalExtension|pod\s+['\"]OneSignal", blob) is not None
+        service = [fp for fp in walk_files(self.root)
+                   if os.path.basename(fp) in ("NotificationService.swift", "NotificationService.m")
+                   and "OneSignalExtension" in read(fp)]
+        missing = []
+        if not target:
+            missing.append("no OneSignalNotificationServiceExtension target in project.pbxproj or Podfile")
+        if not service:
+            missing.append("no NotificationService.swift/.m that forwards to OneSignalExtension")
+        if not linked:
+            missing.append("OneSignalExtension (SPM) or the OneSignal pod is not linked to the extension")
+        self.add("ios_nse_present", not missing, "warn",
+                 "" if not missing else "; ".join(missing) + " (ios-nse.md)")
+
+    def ios_app_group_matches(self):
+        # Both targets must name the same App Group, or the extension cannot read
+        # the SDK's state and confirmed delivery, badges, and images fail silently.
+        groups = {}
+        for fp in walk_files(self.root):
+            if not fp.endswith(".entitlements"):
+                continue
+            found = set(re.findall(r"<string>\s*(group\.[^<\s]+)\s*</string>", read(fp)))
+            if found:
+                groups[os.path.relpath(fp, self.root)] = found
+        nse = {k: v for k, v in groups.items() if "OneSignalNotificationServiceExtension" in k}
+        app = {k: v for k, v in groups.items() if k not in nse}
+        if not nse:
+            self.add("ios_app_group_matches", False, "warn",
+                     "no App Group in the OneSignalNotificationServiceExtension entitlements (ios-nse.md)")
+            return
+        if not app:
+            self.add("ios_app_group_matches", False, "warn",
+                     "no App Group in the main app target's entitlements (ios-nse.md)")
+            return
+        nse_groups = set().union(*nse.values())
+        app_groups = set().union(*app.values())
+        ok = bool(nse_groups & app_groups)
+        self.add("ios_app_group_matches", ok, "error",
+                 "" if ok else "the App Group differs between the app (%s) and the extension (%s); "
+                 "both must name the same group" % (", ".join(sorted(app_groups)), ", ".join(sorted(nse_groups))))
+
     # ---- expo / react-native (shared package: react-native-onesignal) ----
     def rn_package_present(self):
         pkgs = [fp for fp in walk_files(self.root) if os.path.basename(fp) == "package.json"]
@@ -596,7 +647,8 @@ def run(self):
             # structurally assert), so it runs the universal checks only.
             "unity": [],
             "ios": [self.ios_init_in_launch, self.ios_verification_debug_guarded,
-                    self.ios_verification_uses_push_observer],
+                    self.ios_verification_uses_push_observer, self.ios_nse_present,
+                    self.ios_app_group_matches],
             "expo": [self.expo_plugin_registered, self.expo_plugin_first,
                      self.rn_package_present, self.rn_init_present, self.rn_verification_dev_guarded],
             "react-native": [self.rn_package_present, self.rn_init_present, self.rn_verification_dev_guarded],
diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md
index 44601af..a8da482 100644
--- a/skills/setup/SKILL.md
+++ b/skills/setup/SKILL.md
@@ -295,7 +295,7 @@ Open the platform reference file for the detected platform and follow its instal
 - the dependency manifest (package.json / Podfile / build.gradle(.kts) / pubspec.yaml / app.json)
 - the SDK init / lifecycle file (AppDelegate, Application subclass, `App.tsx`/`_layout.tsx`, `main.dart`, `<head>`/root layout for web)
 - ONE centralized wrapper module (see below)
-- platform config files strictly required by the matrix (AndroidManifest, Info.plist + pbxproj, entitlements, web service worker in `public/`)
+- platform config files strictly required by the matrix (AndroidManifest, Info.plist + pbxproj, entitlements, the iOS `OneSignalNotificationServiceExtension/` folder, web service worker in `public/`)
 - ONE debug-only verification helper file
 - `.gitignore` and, if needed, `.env` + `.env.example`
 
diff --git a/skills/setup/assets/ios/NotificationService.swift.tmpl b/skills/setup/assets/ios/NotificationService.swift.tmpl
new file mode 100644
index 0000000..991a60b
--- /dev/null
+++ b/skills/setup/assets/ios/NotificationService.swift.tmpl
@@ -0,0 +1,43 @@
+// onesignal:managed v1
+// File: OneSignalNotificationServiceExtension/NotificationService.swift
+// The principal class of the OneSignalNotificationServiceExtension target.
+// OneSignal downloads and attaches images, reports confirmed delivery, and
+// sets badge counts from here. The extension shares an App Group with the
+// main app target; without the same group in both targets, these features
+// fail silently while plain pushes still arrive.
+import UserNotifications
+import OneSignalExtension
+
+class NotificationService: UNNotificationServiceExtension {
+
+    var contentHandler: ((UNNotificationContent) -> Void)?
+    var receivedRequest: UNNotificationRequest!
+    var bestAttemptContent: UNMutableNotificationContent?
+
+    override func didReceive(
+        _ request: UNNotificationRequest,
+        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
+    ) {
+        self.receivedRequest = request
+        self.contentHandler = contentHandler
+        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
+
+        if let bestAttemptContent = bestAttemptContent {
+            OneSignalExtension.didReceiveNotificationExtensionRequest(
+                self.receivedRequest,
+                with: bestAttemptContent,
+                withContentHandler: self.contentHandler
+            )
+        }
+    }
+
+    override func serviceExtensionTimeWillExpire() {
+        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
+            OneSignalExtension.serviceExtensionTimeWillExpireRequest(
+                self.receivedRequest,
+                with: self.bestAttemptContent
+            )
+            contentHandler(bestAttemptContent)
+        }
+    }
+}
diff --git a/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl b/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl
new file mode 100644
index 0000000..ca3cd8f
--- /dev/null
+++ b/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>OneSignalNotificationServiceExtension</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.usernotifications.service</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).NotificationService</string>
+	</dict>
+</dict>
+</plist>
diff --git a/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl b/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl
new file mode 100644
index 0000000..0c83383
--- /dev/null
+++ b/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.__MAIN_APP_BUNDLE_ID__.onesignal</string>
+	</array>
+</dict>
+</plist>
diff --git a/skills/setup/ios-nse.md b/skills/setup/ios-nse.md
new file mode 100644
index 0000000..5880a02
--- /dev/null
+++ b/skills/setup/ios-nse.md
@@ -0,0 +1,237 @@
+# iOS Notification Service Extension and App Group
+
+Reference for the `setup` skill, loaded from [ios.md](ios.md). The Notification Service Extension (NSE) and the App Group are part of the default native iOS install: images, action buttons, badge counts, and confirmed delivery all run inside the extension, and the extension reads the SDK's state through the App Group. Without them a plain push still arrives, so the omission is silent. `<plugin>` has the meaning [SKILL.md](SKILL.md) defines.
+
+## Required outcomes
+
+- The `OneSignalNotificationServiceExtension` target exists and builds.
+- The NSE target links `OneSignalExtension` (SPM) or the `OneSignal/OneSignal` pod (CocoaPods).
+- The App Group `group.<MAIN_APP_BUNDLE_ID>.onesignal` is in the entitlements of **both** the main app target and the NSE target, with the same string.
+- The NSE deployment target equals the main app target's.
+- `NotificationService` forwards to `OneSignalExtension.didReceiveNotificationExtensionRequest`.
+- The main app embeds the `.appex` in an `Embed Foundation Extensions` build phase.
+
+## App Group rules
+
+Build the group name from the **main app target's** Bundle ID, never the extension's:
+
+- Correct: `group.com.example.myapp.onesignal`
+- Wrong: `group.com.example.myapp.OneSignalNotificationServiceExtension.onesignal`
+
+If the project already uses a different App Group for OneSignal, keep it, and add `OneSignal_app_groups_key` with that name to the `Info.plist` of both targets. With automatic signing, Xcode registers the group with the Apple team on the next device build; a physical-device build still needs a valid team.
+
+## Files — write the 3 templates as-is
+
+Create `OneSignalNotificationServiceExtension/` next to the `.xcodeproj` and write:
+
+| Template | Destination | Substitution |
+|---|---|---|
+| [assets/ios/NotificationService.swift.tmpl](assets/ios/NotificationService.swift.tmpl) | `OneSignalNotificationServiceExtension/NotificationService.swift` | none |
+| [assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl](assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl) | `OneSignalNotificationServiceExtension/Info.plist` | none |
+| [assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl](assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl) | `OneSignalNotificationServiceExtension/OneSignalNotificationServiceExtension.entitlements` | `__MAIN_APP_BUNDLE_ID__` → the main app target's Bundle ID |
+
+Do not hand-write `NotificationService.swift`: the plugin repository compile-checks the template against a stub of `OneSignalExtension.h`, and the 2 calls in it are the only ones the extension needs. Use Swift unless the project is Objective-C only; for an Objective-C project, set `NSExtensionPrincipalClass` to `NotificationService` without the `$(PRODUCT_MODULE_NAME).` prefix.
+
+Add the same App Group to the **main app** `.entitlements`, next to `aps-environment`:
+
+```xml
+<key>com.apple.security.application-groups</key>
+<array>
+	<string>group.MAIN_APP_BUNDLE_ID.onesignal</string>
+</array>
+```
+
+## Add the NSE target to `project.pbxproj`
+
+Prefer the text edit: the user's host usually has no Xcode UI, and the objects below are what File ▸ New ▸ Target writes. Preview them in the Step-5 diff like every other pbxproj edit (safety contract §5). If the pbxproj format does not match the shapes below, stop the edit and hand the target creation to the human (File ▸ New ▸ Target ▸ Notification Service Extension, named `OneSignalNotificationServiceExtension`); then still write the 3 files, the App Group, and the product link, and report `setup.platform_config fail capability_manual` ([ios.md](ios.md) → Checkpoint).
+
+Every object needs a unique 24-character hex ID. The placeholders `NSE0000000000000000000X` below stand for IDs you generate; check that none collides with an existing ID. Replace `MAIN_APP_BUNDLE_ID`, `<PROJECT_OBJECT_ID>`, and the deployment target with the project's values.
+
+### 1. Product reference
+
+```text
+NSE0000000000000000000A /* OneSignalNotificationServiceExtension.appex */ = {isa = PBXFileReference; explicitFileType = "wrapper.app-extension"; includeInIndex = 0; path = OneSignalNotificationServiceExtension.appex; sourceTree = BUILT_PRODUCTS_DIR; };
+```
+
+Add the reference to the `children` list of the `Products` `PBXGroup`.
+
+### 2. Native target and build phases
+
+```text
+NSE0000000000000000000E /* OneSignalNotificationServiceExtension */ = {
+	isa = PBXNativeTarget;
+	buildConfigurationList = NSE0000000000000000000F /* Build configuration list */;
+	buildPhases = (
+		NSE0000000000000000000B /* Sources */,
+		NSE0000000000000000000C /* Frameworks */,
+		NSE0000000000000000000D /* Resources */,
+	);
+	buildRules = (
+	);
+	dependencies = (
+	);
+	name = OneSignalNotificationServiceExtension;
+	productName = OneSignalNotificationServiceExtension;
+	productReference = NSE0000000000000000000A /* OneSignalNotificationServiceExtension.appex */;
+	productType = "com.apple.product-type.app-extension";
+};
+NSE0000000000000000000B /* Sources */ = {
+	isa = PBXSourcesBuildPhase;
+	buildActionMask = 2147483647;
+	files = (
+	);
+	runOnlyForDeploymentPostprocessing = 0;
+};
+NSE0000000000000000000C /* Frameworks */ = {
+	isa = PBXFrameworksBuildPhase;
+	buildActionMask = 2147483647;
+	files = (
+	);
+	runOnlyForDeploymentPostprocessing = 0;
+};
+NSE0000000000000000000D /* Resources */ = {
+	isa = PBXResourcesBuildPhase;
+	buildActionMask = 2147483647;
+	files = (
+	);
+	runOnlyForDeploymentPostprocessing = 0;
+};
+```
+
+Add `NSE0000000000000000000E` to the `targets` list of the `PBXProject` object.
+
+### 3. File group for the NSE folder
+
+**Xcode 16+ synchronized-group projects** (the pbxproj already has `PBXFileSystemSynchronizedRootGroup` objects): add a synchronized group, and exclude `Info.plist` and the entitlements file from the resource copy, or the build fails with "Multiple commands produce Info.plist".
+
+```text
+NSE00000000000000000012 /* OneSignalNotificationServiceExtension */ = {
+	isa = PBXFileSystemSynchronizedRootGroup;
+	exceptions = (
+		NSE00000000000000000013 /* PBXFileSystemSynchronizedBuildFileExceptionSet */,
+	);
+	path = OneSignalNotificationServiceExtension;
+	sourceTree = "<group>";
+};
+NSE00000000000000000013 /* PBXFileSystemSynchronizedBuildFileExceptionSet */ = {
+	isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
+	membershipExceptions = (
+		Info.plist,
+		OneSignalNotificationServiceExtension.entitlements,
+	);
+	target = NSE0000000000000000000E /* OneSignalNotificationServiceExtension */;
+};
+```
+
+Add the group to the main `PBXGroup`'s `children`, and set `fileSystemSynchronizedGroups = ( NSE00000000000000000012 /* OneSignalNotificationServiceExtension */, );` on the NSE native target.
+
+**Classic projects** (`PBXGroup` / `PBXFileReference`): add a `PBXFileReference` for each of the 3 files, group them in a `PBXGroup` under the main group, and add a `PBXBuildFile` for `NotificationService.swift` to the NSE `Sources` phase's `files`. Do not add `Info.plist` or the entitlements file to any build phase.
+
+### 4. Build configurations
+
+Copy `IPHONEOS_DEPLOYMENT_TARGET`, `SWIFT_VERSION`, `DEVELOPMENT_TEAM`, and the signing style from the main app target. Debug and Release are identical except for `name`.
+
+```text
+NSE00000000000000000010 /* Debug */ = {
+	isa = XCBuildConfiguration;
+	buildSettings = {
+		CODE_SIGN_ENTITLEMENTS = OneSignalNotificationServiceExtension/OneSignalNotificationServiceExtension.entitlements;
+		CODE_SIGN_STYLE = Automatic;
+		CURRENT_PROJECT_VERSION = 1;
+		GENERATE_INFOPLIST_FILE = YES;
+		INFOPLIST_FILE = OneSignalNotificationServiceExtension/Info.plist;
+		IPHONEOS_DEPLOYMENT_TARGET = 17.0; /* the MAIN APP target's value */
+		LD_RUNPATH_SEARCH_PATHS = (
+			"$(inherited)",
+			"@executable_path/Frameworks",
+			"@executable_path/../../Frameworks",
+		);
+		MARKETING_VERSION = 1.0;
+		PRODUCT_BUNDLE_IDENTIFIER = MAIN_APP_BUNDLE_ID.OneSignalNotificationServiceExtension;
+		PRODUCT_NAME = "$(TARGET_NAME)";
+		SKIP_INSTALL = YES;
+		SWIFT_EMIT_LOC_STRINGS = YES;
+		SWIFT_VERSION = 5.0;
+		TARGETED_DEVICE_FAMILY = "1,2";
+	};
+	name = Debug;
+};
+NSE0000000000000000000F /* Build configuration list for PBXNativeTarget "OneSignalNotificationServiceExtension" */ = {
+	isa = XCConfigurationList;
+	buildConfigurations = (
+		NSE00000000000000000010 /* Debug */,
+		NSE00000000000000000011 /* Release */,
+	);
+	defaultConfigurationIsVisible = 0;
+	defaultConfigurationName = Release;
+};
+```
+
+### 5. Embed the extension in the main app target
+
+```text
+NSE00000000000000000016 /* PBXContainerItemProxy */ = {
+	isa = PBXContainerItemProxy;
+	containerPortal = <PROJECT_OBJECT_ID> /* Project object */;
+	proxyType = 1;
+	remoteGlobalIDString = NSE0000000000000000000E;
+	remoteInfo = OneSignalNotificationServiceExtension;
+};
+NSE00000000000000000017 /* PBXTargetDependency */ = {
+	isa = PBXTargetDependency;
+	target = NSE0000000000000000000E /* OneSignalNotificationServiceExtension */;
+	targetProxy = NSE00000000000000000016 /* PBXContainerItemProxy */;
+};
+NSE00000000000000000014 /* OneSignalNotificationServiceExtension.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = NSE0000000000000000000A /* OneSignalNotificationServiceExtension.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
+NSE00000000000000000015 /* Embed Foundation Extensions */ = {
+	isa = PBXCopyFilesBuildPhase;
+	buildActionMask = 2147483647;
+	dstPath = "";
+	dstSubfolderSpec = 13;
+	files = (
+		NSE00000000000000000014 /* OneSignalNotificationServiceExtension.appex in Embed Foundation Extensions */,
+	);
+	name = "Embed Foundation Extensions";
+	runOnlyForDeploymentPostprocessing = 0;
+};
+```
+
+On the **main app** target, append `NSE00000000000000000015 /* Embed Foundation Extensions */` to `buildPhases` after `Resources`, and `NSE00000000000000000017 /* PBXTargetDependency */` to `dependencies`.
+
+### 6. Link the OneSignal product to the NSE target
+
+**SPM:**
+
+```text
+NSE00000000000000000008 /* OneSignalExtension */ = {
+	isa = XCSwiftPackageProductDependency;
+	package = <ONESIGNAL_PACKAGE_REFERENCE_ID> /* XCRemoteSwiftPackageReference "OneSignal-XCFramework" */;
+	productName = OneSignalExtension;
+};
+NSE00000000000000000009 /* OneSignalExtension in Frameworks */ = {isa = PBXBuildFile; productRef = NSE00000000000000000008 /* OneSignalExtension */; };
+```
+
+Add the `PBXBuildFile` to the NSE `Frameworks` phase's `files`, and `packageProductDependencies = ( NSE00000000000000000008 /* OneSignalExtension */, );` to the NSE native target. The `XCRemoteSwiftPackageReference` for `https://github.com/OneSignal/OneSignal-XCFramework` is the one the app target already uses ([ios.md](ios.md) → Dependency); add it to the `PBXProject`'s `packageReferences` first if the project has none.
+
+**CocoaPods:** skip the SPM objects. Add the NSE target block to the `Podfile` with the resolver's `--line-format podfile-nse` output, then run `pod install`:
+
+```ruby
+target 'OneSignalNotificationServiceExtension' do
+  pod 'OneSignal/OneSignal', 'X.Y.Z' # onesignal:managed v1 — the resolver's exact pin, the same as the app target
+end
+```
+
+### 7. Check the edit
+
+Run `xcodebuild -list -project <App>.xcodeproj`. A malformed pbxproj fails at once; a good one lists both targets. Then build with `-scmProvider system` ([ios.md](ios.md)): no `No such module 'OneSignalExtension'`, and the built app has `PlugIns/OneSignalNotificationServiceExtension.appex`. Keep code signing on: a build with signing disabled drops `aps-environment` and the App Group from the binary, and the SDK then reports the Push capability as missing.
+
+## Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| Push arrives, image missing | The NSE is absent or does not run: check the target exists, embeds in the app, links `OneSignalExtension`, and matches the app's deployment target |
+| No confirmed delivery | The App Group differs between the targets, the NSE is missing, or the plan does not show it (paid plans only) |
+| Badge does not update | The App Groups capability is missing from one target |
+| `No such module 'OneSignalExtension'` | The product or pod is not linked to the NSE target |
+| "Multiple commands produce Info.plist" | Exclude `Info.plist` through the `PBXFileSystemSynchronizedBuildFileExceptionSet` (step 3) |
+| App Group works in the simulator, fails on a device | Select a valid Apple team so Xcode registers the group, or register it in the Apple Developer portal |
diff --git a/skills/setup/ios.md b/skills/setup/ios.md
index e8ca7d6..087bbb8 100644
--- a/skills/setup/ios.md
+++ b/skills/setup/ios.md
@@ -4,15 +4,26 @@ Reference for the `setup` skill. Follow [SKILL.md](SKILL.md) Steps 0–8; this f
 
 ## What the agent does vs. the human (matrix)
 
-- **Agent (text-editable):** add the SPM package or Podfile line; `OneSignal.initialize(appId, withLaunchOptions:)` in `AppDelegate` / SwiftUI `init()`; `Info.plist` `UIBackgroundModes = remote-notification`; the two `project.pbxproj` build settings; entitlements text; wrapper + debug-only verification helper.
+- **Agent (text-editable):** add the SPM package products or Podfile lines; `OneSignal.initialize(appId, withLaunchOptions:)` in `AppDelegate` / SwiftUI `init()`; `Info.plist` `UIBackgroundModes = remote-notification`; the two `project.pbxproj` build settings; entitlements text (`aps-environment` + the App Group); the Notification Service Extension folder (3 template files) and its pbxproj target objects ([ios-nse.md](ios-nse.md)); wrapper + debug-only verification helper.
 - **Human (Xcode GUI + Apple portal — you CANNOT reliably do these):**
   - Apple Developer portal (paid account): enable the **Push Notifications** capability on the App ID, generate an **APNs `.p8`** key + capture Key ID + Team ID → handed to the **credentials** skill.
-  - Xcode GUI: signing, the Push Notifications + Background Modes capability toggles, and — if needed — **Notification Service Extension target creation** (File ▸ New ▸ Target). NSE is NOT reliably text-editable; guide the human.
+  - Xcode GUI: signing and the Push Notifications + Background Modes capability toggles. **Notification Service Extension target creation** (File ▸ New ▸ Target) only as the fallback when the pbxproj format does not match the shapes in ios-nse.md.
   - Test on a **physical device** (signing + device trust are Xcode-GUI-bound). A simulator on an Apple-silicon Mac is NOT a human step — the verify skill boots, installs, and launches it unattended (Xcode 14+ simulators there receive real sandbox APNs pushes; Intel-Mac simulators do not receive remote push). Only the notification permission tap stays with the human.
 
-## NSE is OPTIONAL for a minimal install
+## NSE and App Group are part of the default install
 
-A Notification Service Extension is only needed for rich media, confirmed delivery, or badges. OneSignal's own AI prompt skips it for minimal install — so do NOT create an NSE unless the user asks for those features. Keep the integration minimal (safety contract §8).
+Images, action buttons, badge counts, and confirmed delivery all run inside the **Notification Service Extension**, and the extension reads the SDK's state through an **App Group** shared with the main app. A plain push still arrives without them, so a missing extension fails silently. Create both on every native iOS install (safety contract §8 names them as part of the minimal integration); the recipe is [ios-nse.md](ios-nse.md). Add nothing else: no in-app message code, no location prompt, no notification-click handler.
+
+## Which SDK products
+
+The documentation names 4 SPM products and the pod subspecs that match them. The default set, and the reason for each:
+
+| Product | Target | Default |
+|---|---|---|
+| `OneSignalFramework` | app | yes — the SDK |
+| `OneSignalInAppMessages` | app | yes — the documentation recommends it; the module needs no code and no permission, and in-app messages sent from the dashboard render only when it is linked |
+| `OneSignalExtension` | `OneSignalNotificationServiceExtension` | yes — the NSE links it ([ios-nse.md](ios-nse.md)) |
+| `OneSignalLocation` | app | **no** — it adds location tracking and the location permission prompt. Add it only when the user's request names location; otherwise mention in the Step-8 summary, in one sentence, that it exists |
 
 ## Dependency
 
@@ -20,17 +31,28 @@ Detect the existing manager: `Podfile`/`Podfile.lock` → CocoaPods; `Package.sw
 
 ```bash
 python3 <plugin>/scripts/resolve_sdk_version.py ios --format json   # for the version
-python3 <plugin>/scripts/resolve_sdk_version.py ios --format line --line-format podfile   # Podfile line
+python3 <plugin>/scripts/resolve_sdk_version.py ios --format line --line-format podfile       # app target Podfile lines
+python3 <plugin>/scripts/resolve_sdk_version.py ios --format line --line-format podfile-nse   # NSE target Podfile line
 ```
 
-**Swift Package Manager** (smaller XCFramework download — matrix): add package `https://github.com/OneSignal/OneSignal-XCFramework` with an **Exact Version** rule set to the resolver's `version`, and add the **`OneSignalFramework`** library product to the app target (add `OneSignalInAppMessages` / `OneSignalLocation` only if those features are wanted). SPM add is partly GUI — if you cannot edit the pbxproj package references safely, give the human the exact File ▸ Add Packages steps.
+The feed entry is the `OneSignal-iOS-SDK` repository; the SPM package is `OneSignal-XCFramework`, which publishes the same version tags, so the resolver's `version` is the pin for both (the script says so in its `note`).
+
+**Swift Package Manager:** add the package `https://github.com/OneSignal/OneSignal-XCFramework` — **not** `OneSignal-iOS-SDK`, which is the source repository and makes Xcode build the whole SDK — with an **Exact Version** rule set to the resolver's `version`. Map the products per "Which SDK products" above: `OneSignalFramework` and `OneSignalInAppMessages` on the app target, `OneSignalExtension` on the `OneSignalNotificationServiceExtension` target. The most common install mistake is a product on the wrong target: `No such module 'OneSignalFramework'` means the app target lacks it; `No such module 'OneSignalExtension'` means the NSE target lacks it. SPM add is a pbxproj edit (`XCRemoteSwiftPackageReference` + one `XCSwiftPackageProductDependency` per product) — if you cannot edit the package references safely, give the human the exact File ▸ Add Package Dependencies steps with the URL, the version, and the product-to-target table.
 
 **CLI builds + SPM keychain wall:** `xcodebuild`-driven SPM resolution can pop a macOS **login-keychain password prompt** (and re-prompt on Deny), which stalls headless/agent runs. Pass `-scmProvider system` to `xcodebuild` so package fetching uses system git credentials instead of Xcode's keychain-backed SCM.
 
-**CocoaPods** (`Podfile`) — paste the resolver's `--line-format podfile` output verbatim (it is an exact pin), then `pod install`. Shape:
+**CocoaPods** (`Podfile`) — paste the resolver's `--line-format podfile` output verbatim into the app target and the `--line-format podfile-nse` output into the NSE target (both are exact pins), then `pod repo update && pod install`, and build the `.xcworkspace`. Shape:
 ```ruby
-pod 'OneSignal/OneSignal', '5.5.1' # onesignal:managed v1
+target 'YourApp' do
+  pod 'OneSignal/OneSignal', 'X.Y.Z' # onesignal:managed v1
+  pod 'OneSignal/OneSignalInAppMessages', 'X.Y.Z' # onesignal:managed v1
+end
+
+target 'OneSignalNotificationServiceExtension' do
+  pod 'OneSignal/OneSignal', 'X.Y.Z' # onesignal:managed v1
+end
 ```
+The `OneSignal` pod vendors the same XCFrameworks as the SPM package, so CocoaPods needs no repository change. CocoaPods 1.16.2+ is required; on an Xcode 16 project, `Unable to find compatibility version string for object version '70'` means the `xcodeproj` gem is too old — the documented workaround is to set `objectVersion = 55;` in the pbxproj before `pod install`.
 
 ## Initialize at launch
 
@@ -55,9 +77,13 @@ SwiftUI `@main` app with no AppDelegate: call the same two lines from the `App`'
    INFOPLIST_FILE = "YourApp/Info.plist";
    INFOPLIST_KEY_UIBackgroundModes = "remote-notification";
    ```
-3. For Xcode 16+ file-system-synchronized projects (`PBXFileSystemSynchronizedRootGroup`), add a `PBXFileSystemSynchronizedBuildFileExceptionSet` excluding `Info.plist` from the resource copy phase to avoid "Multiple commands produce Info.plist". Skip step 3 for classic `PBXGroup`/`PBXFileReference` projects. The exact pbxproj snippets are in the upstream ios/integrate.md — reproduce them; pbxproj edits are fragile, so preview them precisely in the diff (safety contract §5) and if the format doesn't match, hand the capability toggle to the human via Xcode's Signing & Capabilities tab instead.
+3. For Xcode 16+ file-system-synchronized projects (`PBXFileSystemSynchronizedRootGroup`), add a `PBXFileSystemSynchronizedBuildFileExceptionSet` excluding `Info.plist` from the resource copy phase to avoid "Multiple commands produce Info.plist". Skip step 3 for classic `PBXGroup`/`PBXFileReference` projects. The `PBXFileSystemSynchronizedBuildFileExceptionSet` shape is the one in [ios-nse.md](ios-nse.md) step 3, with the app target and `Info.plist` in place of the extension's values; pbxproj edits are fragile, so preview them precisely in the diff (safety contract §5) and if the format doesn't match, hand the capability toggle to the human via Xcode's Signing & Capabilities tab instead.
+
+Add `aps-environment` to the `.entitlements` file (`development`, or `production` for release), and the App Group `group.<MAIN_APP_BUNDLE_ID>.onesignal` next to it ([ios-nse.md](ios-nse.md) → "App Group rules"). If the target has no `CODE_SIGN_ENTITLEMENTS` setting yet, add it to the Debug and Release configurations, and on an Xcode 16+ synchronized project list the entitlements file in the same `membershipExceptions` as `Info.plist`. Deployment target iOS 12.0+; do not change it if already set.
+
+## Notification Service Extension + App Group
 
-Add `aps-environment` to the `.entitlements` file (`development`, or `production` for release). Deployment target iOS 12.0+; do not change it if already set.
+Follow [ios-nse.md](ios-nse.md): write the 3 template files into `OneSignalNotificationServiceExtension/`, add the target objects to `project.pbxproj` (or hand the target creation to the human when the format does not match), link `OneSignalExtension` (SPM) or the NSE pod block (CocoaPods), and put the same App Group in both entitlements files. The NSE folder, its 3 files, and the pbxproj objects belong in the Step-5 allow-list and diff.
 
 ## Centralized wrapper (Swift)
 
@@ -70,7 +96,7 @@ Use the verified template [assets/ios/OneSignalSetupVerification.swift.tmpl](ass
 - register with `OneSignal.User.pushSubscription.addObserver(self)`; also read `OneSignal.User.pushSubscription.id` immediately (race guard).
 - `requestPermission` on iOS DOES take a completion block: `OneSignal.Notifications.requestPermission({ accepted in ... }, fallbackToSettings: false)` (unlike Android's suspend form).
 
-The Step-8 structural self-check (`verify_integration.py --platform ios`) enforces `#if DEBUG`, the real push observer (not NotificationCenter), and init in a launch context. Non-negotiable properties (SKILL.md Step 6):
+The Step-8 structural self-check (`verify_integration.py --platform ios`) enforces `#if DEBUG`, the real push observer (not NotificationCenter), init in a launch context, the NSE target with `OneSignalExtension` linked, and one App Group shared by the app and extension entitlements. Non-negotiable properties (SKILL.md Step 6):
 - Guard on `#if DEBUG` so it never ships.
 - `OneSignal.Notifications.requestPermission(..., fallbackToSettings: false)` at install — the ONLY permission prompt. `fallbackToSettings` stays `false`: the call runs at launch with no user gesture, and `true` would send a previously-denied user to the Settings app on every debug start.
 - Register the observer AND call `evaluate(OneSignal.User.pushSubscription.id)` immediately (race guard).
@@ -79,23 +105,24 @@ The Step-8 structural self-check (`verify_integration.py --platform ios`) enforc
 - No dialog and no network call — the verify skill confirms the subscription server-side and sends the test push from chat.
 - Top-of-file comment naming the file + call site, and saying the file is debug-only and safe to keep.
 
-## Checkpoint — `setup.platform_config` (capabilities + permission request)
+## Checkpoint — `setup.platform_config` (capabilities + permission request + extension)
 
 Report the iOS push prerequisites right after `setup.verification_added`, once the
 Step-5 change set and the verification helper both exist (telemetry contract rules
 apply, consent included). Run exactly one of:
 
-- All 4 prerequisites are in place — `UIBackgroundModes` `remote-notification`, the
-  `aps-environment` entitlement, the pbxproj build settings, and the `requestPermission`
-  call in the helper:
+- All 6 prerequisites are in place — `UIBackgroundModes` `remote-notification`, the
+  `aps-environment` entitlement, the pbxproj build settings, the `requestPermission`
+  call in the helper, the `OneSignalNotificationServiceExtension` target with
+  `OneSignalExtension` linked, and the same App Group in both entitlements files:
   `bash <plugin>/scripts/checkpoint.sh setup.platform_config ok`
-- The pbxproj format did not match and you handed the capability toggles to the human
-  via Xcode's Signing & Capabilities tab:
+- The pbxproj format did not match and you handed the capability toggles or the NSE
+  target creation to the human in Xcode:
   `bash <plugin>/scripts/checkpoint.sh setup.platform_config fail capability_manual`
   — report it at the hand-off and continue; the fail row records the drop out of agent
   automation, not a skill stop.
 
 ## Handoffs
 
-- Hand off to **credentials** — iOS push needs the APNs `.p8` (+ Key ID/Team ID) on the OneSignal app, and the human must toggle capabilities + create the NSE in Xcode if rich features are wanted.
+- Hand off to **credentials** — iOS push needs the APNs `.p8` (+ Key ID/Team ID) on the OneSignal app, and the human must toggle capabilities in Xcode (and create the NSE target when you handed that step over).
 - Then **verify** — on an Apple-silicon Mac the verify skill runs the simulator itself; a physical device needs the human to launch from Xcode.
diff --git a/skills/verify/platform-verification.md b/skills/verify/platform-verification.md
index a121bd3..00fdeec 100644
--- a/skills/verify/platform-verification.md
+++ b/skills/verify/platform-verification.md
@@ -92,7 +92,7 @@ Diagnose in this ranked order. For each: symptom → most-likely cause → fix /
 - **Simulator:** Intel-Mac simulators do not receive remote push — use a **physical device or a simulator on an Apple-silicon Mac** (Xcode 14+ simulators there receive real sandbox APNs pushes and register normally).
 - **APNs credentials (.p8) missing or not propagated block *delivery*, not registration** on the v5 SDK — the subscription row comes from the server-side user create, independent of platform credentials (verified in SDK source, not yet live-tested). Expect that gap as `errored` at step 5; a true step-2 timeout points at the app never running or init never firing, or at the other items here. New keys take 10–15 min to propagate (the credentials skill uploads the .p8 + Key ID + Team ID). The **Push capability** on the App ID / provisioning profile is a different failure: without it the token fetch itself fails (APNS 3000, next bullet).
 - **"APNS delegate never fired" / "APNS 3000":** usually a second push SDK or native push API alongside OneSignal, or transient connectivity that self-resolves after a new session (background 30s+, reopen). Remove other push dependencies; for **Capacitor** set `ios.handleApplicationNotifications: false`.
-- Confirmed receipt (`received`) additionally needs the **NSE + App Group** — but that is optional for a minimal install; do not treat its absence as a registration failure.
+- Confirmed receipt (`received`) additionally needs the **NSE + App Group** — part of the default native iOS install, optional on the wrapper frameworks; do not treat its absence as a registration failure.
 
 ### 4. Android — device never registers
 **Symptom:** step 2 times out on Android.

From 16d104bfa7c5d20a68a68a189073109fac74609e Mon Sep 17 00:00:00 2001
From: sherwinski <sherwin@onesignal.com>
Date: Wed, 28 Oct 2026 10:13:43 -0700
Subject: [PATCH 3/6] feat: ask native iOS users whether to add
 OneSignalLocation

The documentation marks OneSignalLocation as optional, so setup now asks
one structured question before the Step-5 diff and adds the module only
on a yes. The question is skipped when the request already answers it or
a prior install links the module.

On a yes, the change set gains the product (or the new podfile-location
resolver line), NSLocationWhenInUseUsageDescription, and
OneSignal.Location.isShared = true after initialize, because the SDK
defaults sharing to off. Setup still adds no location prompt at launch;
the summary names the in-app message prompt and requestPermission().

verify_integration.py warns when OneSignalLocation is linked without a
location usage description.
---
 references/platform-matrix.md  |  2 +-
 references/safety-contract.md  |  4 ++--
 scripts/resolve_sdk_version.py |  4 +++-
 scripts/verify_integration.py  | 21 ++++++++++++++++++++-
 skills/setup/SKILL.md          |  2 +-
 skills/setup/ios.md            | 33 ++++++++++++++++++++++++++++-----
 6 files changed, 55 insertions(+), 11 deletions(-)

diff --git a/references/platform-matrix.md b/references/platform-matrix.md
index f1a0a80..6cb61a8 100644
--- a/references/platform-matrix.md
+++ b/references/platform-matrix.md
@@ -9,7 +9,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. |
-| **iOS native** | SPM (`OneSignal-XCFramework` repo — never `OneSignal-iOS-SDK`; `OneSignalFramework` + `OneSignalInAppMessages`→app, `OneSignalExtension`→NSE) or Podfile (`OneSignal/OneSignal` + `OneSignal/OneSignalInAppMessages` on the app target, `OneSignal/OneSignal` on the NSE target); `OneSignal.initialize(appId, withLaunchOptions:)` in AppDelegate/adaptor; Info.plist `UIBackgroundModes remote-notification`; entitlements text (`aps-environment` + App Group); the NSE folder (3 templates) and its pbxproj target objects; 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) only when the pbxproj format does not match the recipe; physical-device test (launch from Xcode) + the notification permission tap | NSE + App Group are part of the default install (images, badges, confirmed receipt fail silently without them); `OneSignalLocation` only on request. 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. |
+| **iOS native** | SPM (`OneSignal-XCFramework` repo — never `OneSignal-iOS-SDK`; `OneSignalFramework` + `OneSignalInAppMessages`→app, `OneSignalExtension`→NSE) or Podfile (`OneSignal/OneSignal` + `OneSignal/OneSignalInAppMessages` on the app target, `OneSignal/OneSignal` on the NSE target); `OneSignal.initialize(appId, withLaunchOptions:)` in AppDelegate/adaptor; Info.plist `UIBackgroundModes remote-notification`; entitlements text (`aps-environment` + App Group); the NSE folder (3 templates) and its pbxproj target objects; 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) only when the pbxproj format does not match the recipe; physical-device test (launch from Xcode) + the notification permission tap | NSE + App Group are part of the default install (images, badges, confirmed receipt fail silently without them); `OneSignalLocation` only on an opt-in (one question before the diff). 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/references/safety-contract.md b/references/safety-contract.md
index 7736c87..7d4615c 100644
--- a/references/safety-contract.md
+++ b/references/safety-contract.md
@@ -14,7 +14,7 @@ Any skill that reads or writes the user's repository MUST follow all of this. It
 5. Compute the FULL change set and show it as diffs BEFORE any write. One confirmation for the whole set. Apply exactly as previewed; if a file drifted, abort that file and re-preview.
 6. Mark generated blocks: `// onesignal:managed v1` — idempotency keys off this marker on re-runs.
 7. Match the repo's style, package manager (detect via lockfile), and architecture. No repo-wide reformatting, no unrelated dep bumps, no import reordering.
-8. Minimal integration only: init + permission in the right lifecycle spot. No extra OneSignal features unless asked. On native iOS the minimal integration includes the Notification Service Extension, the App Group, and the `OneSignalInAppMessages` product: without the first two, images, badges, and confirmed delivery fail silently, and the third is the documented default with no code of its own. `OneSignalLocation` is an extra feature.
+8. Minimal integration only: init + permission in the right lifecycle spot. No extra OneSignal features unless asked. On native iOS the minimal integration includes the Notification Service Extension, the App Group, and the `OneSignalInAppMessages` product: without the first two, images, badges, and confirmed delivery fail silently, and the third is the documented default with no code of its own. `OneSignalLocation` is an extra feature: the iOS reference asks once, and adds it only on a yes.
 
 ## Never
 
@@ -48,7 +48,7 @@ The onboarding flow can deliver the app-scoped key inside the invocation (`/ones
 
 ## Asking the user (human gates)
 
-14. A human gate (checkpoint consent, dirty-tree stash/proceed/abort, missing App ID, no-VCS backup consent, the pre-write diff confirmation, test-send consent) BLOCKS: do not continue, mutate files, or assume an answer until the user responds. Ask via the harness's native structured-question tool when one exists — Claude Code: `AskUserQuestion`; Codex: `request_user_input` — otherwise ask plainly in chat and end the turn. Call the tool by name; a list of choices written in prose does not render as a selectable prompt. Use structured choices for bounded decisions (stash/proceed/abort, yes/no, pick-a-platform, share-or-keep-local checkpoints). Give each question 2 or 3 options (the Codex limit). When one option is the recommended path, put it first and end its label with "(Recommended)". The checkpoint consent question is the exception: it has no recommended option, and it keeps the order the skill lists, with "Share reports with OneSignal" first. Never add your own "Other" option — both hosts add a free-text "Other" by themselves. Codex in Default mode usually lists only `request_user_input_async`; use it when `request_user_input` is absent. The Codex app shows the async call as a question card with the choices; the Codex CLI shows it as plain text. The async call returns `{"accepted":true}` without the answer, so after it write one plain-text line that names each choice and the exact word to reply with — for example "Reply `share` or `keep`." — and end the turn. If no question tool is listed, or the host rejects the call, write that same plain-text question alone and end the turn. Never pick an answer for the user, and never continue past the gate on `{"accepted":true}`. For free-form values (App ID, Key ID, Team ID, file paths, bundle IDs, URLs), still prefer the structured tool when it accepts typed text (most tools show an "Other" free-text field): the question names the value, the user types it, and every listed option is a fallback route — for example "Help me find it" (repeat the portal location) or "Pause — I'll come back". One question per value, and when several values are pending, batch them as ONE tool call with one entry per value in its `questions` array, at most 3 questions per call (the Codex limit; a longer set goes in consecutive calls) — do not issue parallel single-question calls, which can leave only the last prompt visible — then wait for the answers. Fall back to plain chat only when the tool cannot take free text. Secrets are the exception, always: never make a secret's contents an option or a typed answer — secrets stay file-path-only (see "Never").
+14. A human gate (checkpoint consent, dirty-tree stash/proceed/abort, missing App ID, no-VCS backup consent, the iOS location opt-in, the pre-write diff confirmation, test-send consent) BLOCKS: do not continue, mutate files, or assume an answer until the user responds. Ask via the harness's native structured-question tool when one exists — Claude Code: `AskUserQuestion`; Codex: `request_user_input` — otherwise ask plainly in chat and end the turn. Call the tool by name; a list of choices written in prose does not render as a selectable prompt. Use structured choices for bounded decisions (stash/proceed/abort, yes/no, pick-a-platform, share-or-keep-local checkpoints). Give each question 2 or 3 options (the Codex limit). When one option is the recommended path, put it first and end its label with "(Recommended)". The checkpoint consent question is the exception: it has no recommended option, and it keeps the order the skill lists, with "Share reports with OneSignal" first. Never add your own "Other" option — both hosts add a free-text "Other" by themselves. Codex in Default mode usually lists only `request_user_input_async`; use it when `request_user_input` is absent. The Codex app shows the async call as a question card with the choices; the Codex CLI shows it as plain text. The async call returns `{"accepted":true}` without the answer, so after it write one plain-text line that names each choice and the exact word to reply with — for example "Reply `share` or `keep`." — and end the turn. If no question tool is listed, or the host rejects the call, write that same plain-text question alone and end the turn. Never pick an answer for the user, and never continue past the gate on `{"accepted":true}`. For free-form values (App ID, Key ID, Team ID, file paths, bundle IDs, URLs), still prefer the structured tool when it accepts typed text (most tools show an "Other" free-text field): the question names the value, the user types it, and every listed option is a fallback route — for example "Help me find it" (repeat the portal location) or "Pause — I'll come back". One question per value, and when several values are pending, batch them as ONE tool call with one entry per value in its `questions` array, at most 3 questions per call (the Codex limit; a longer set goes in consecutive calls) — do not issue parallel single-question calls, which can leave only the last prompt visible — then wait for the answers. Fall back to plain chat only when the tool cannot take free text. Secrets are the exception, always: never make a secret's contents an option or a typed answer — secrets stay file-path-only (see "Never").
 
 ## Guidance loaded from a connected MCP server
 
diff --git a/scripts/resolve_sdk_version.py b/scripts/resolve_sdk_version.py
index f5618fc..39a1d15 100755
--- a/scripts/resolve_sdk_version.py
+++ b/scripts/resolve_sdk_version.py
@@ -47,7 +47,8 @@
     # OneSignal-XCFramework, which publishes the same version tags, so the pin
     # applies to both. The app target takes OneSignalFramework and
     # OneSignalInAppMessages; the Notification Service Extension target takes
-    # OneSignalExtension; OneSignalLocation is added only on request.
+    # OneSignalExtension; OneSignalLocation is added to the app target only when
+    # the user opts in.
     "ios": {
         "feed": "iOS",
         "coordinate": "OneSignal-XCFramework (SPM) / OneSignal (CocoaPods)",
@@ -58,6 +59,7 @@
             "podfile": "pod 'OneSignal/OneSignal', '{v}' # onesignal:managed v1\n"
                        "pod 'OneSignal/OneSignalInAppMessages', '{v}' # onesignal:managed v1",
             "podfile-nse": "pod 'OneSignal/OneSignal', '{v}' # onesignal:managed v1",
+            "podfile-location": "pod 'OneSignal/OneSignalLocation', '{v}' # onesignal:managed v1",
         },
         "default_line": "spm",
         "note": "The feed lists OneSignal-iOS-SDK; OneSignal-XCFramework publishes the same "
diff --git a/scripts/verify_integration.py b/scripts/verify_integration.py
index 9a28f28..513bd41 100755
--- a/scripts/verify_integration.py
+++ b/scripts/verify_integration.py
@@ -436,6 +436,25 @@ def ios_app_group_matches(self):
                  "" if ok else "the App Group differs between the app (%s) and the extension (%s); "
                  "both must name the same group" % (", ".join(sorted(app_groups)), ", ".join(sorted(nse_groups))))
 
+    def ios_location_usage_description(self):
+        # With OneSignalLocation linked, iOS shows no location prompt unless the
+        # app declares a usage description, so the module never gets a location.
+        manifests = [fp for fp in walk_files(self.root)
+                     if os.path.basename(fp) in ("project.pbxproj", "Podfile")]
+        blob = "\n".join(read(fp) for fp in manifests)
+        linked = re.search(r"productName\s*=\s*OneSignalLocation|pod\s+['\"]OneSignal/OneSignalLocation",
+                           blob) is not None
+        if not linked:
+            self.add("ios_location_usage_description", True, "warn",
+                     "OneSignalLocation not linked; no usage description required")
+            return
+        key = re.compile(r"NSLocation(WhenInUse|AlwaysAndWhenInUse|Always)UsageDescription")
+        declared = any(key.search(read(fp)) for fp in walk_files(self.root)
+                       if fp.endswith((".plist", "project.pbxproj")))
+        self.add("ios_location_usage_description", declared, "warn",
+                 "" if declared else "OneSignalLocation is linked but no NSLocationWhenInUseUsageDescription "
+                 "is in Info.plist or the build settings; iOS will not show the location prompt (ios.md)")
+
     # ---- expo / react-native (shared package: react-native-onesignal) ----
     def rn_package_present(self):
         pkgs = [fp for fp in walk_files(self.root) if os.path.basename(fp) == "package.json"]
@@ -648,7 +667,7 @@ def run(self):
             "unity": [],
             "ios": [self.ios_init_in_launch, self.ios_verification_debug_guarded,
                     self.ios_verification_uses_push_observer, self.ios_nse_present,
-                    self.ios_app_group_matches],
+                    self.ios_app_group_matches, self.ios_location_usage_description],
             "expo": [self.expo_plugin_registered, self.expo_plugin_first,
                      self.rn_package_present, self.rn_init_present, self.rn_verification_dev_guarded],
             "react-native": [self.rn_package_present, self.rn_init_present, self.rn_verification_dev_guarded],
diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md
index a8da482..5ba0fe0 100644
--- a/skills/setup/SKILL.md
+++ b/skills/setup/SKILL.md
@@ -290,7 +290,7 @@ Prefer the OneSignal MCP server's tools over raw curl for API reads if it is con
 
 ## Step 5 — Declare the allow-list, compute diffs, get ONE approval (safety contract §4–6)
 
-Open the platform reference file for the detected platform and follow its install steps. Before writing anything, **declare the complete file allow-list** for this platform — typically:
+Open the platform reference file for the detected platform and follow its install steps. If the reference asks a product question (native iOS asks about `OneSignalLocation`), ask it before you compute the diffs, so the one approval covers the final change set. Before writing anything, **declare the complete file allow-list** for this platform — typically:
 
 - the dependency manifest (package.json / Podfile / build.gradle(.kts) / pubspec.yaml / app.json)
 - the SDK init / lifecycle file (AppDelegate, Application subclass, `App.tsx`/`_layout.tsx`, `main.dart`, `<head>`/root layout for web)
diff --git a/skills/setup/ios.md b/skills/setup/ios.md
index 087bbb8..94ec29e 100644
--- a/skills/setup/ios.md
+++ b/skills/setup/ios.md
@@ -12,7 +12,7 @@ Reference for the `setup` skill. Follow [SKILL.md](SKILL.md) Steps 0–8; this f
 
 ## NSE and App Group are part of the default install
 
-Images, action buttons, badge counts, and confirmed delivery all run inside the **Notification Service Extension**, and the extension reads the SDK's state through an **App Group** shared with the main app. A plain push still arrives without them, so a missing extension fails silently. Create both on every native iOS install (safety contract §8 names them as part of the minimal integration); the recipe is [ios-nse.md](ios-nse.md). Add nothing else: no in-app message code, no location prompt, no notification-click handler.
+Images, action buttons, badge counts, and confirmed delivery all run inside the **Notification Service Extension**, and the extension reads the SDK's state through an **App Group** shared with the main app. A plain push still arrives without them, so a missing extension fails silently. Create both on every native iOS install (safety contract §8 names them as part of the minimal integration); the recipe is [ios-nse.md](ios-nse.md). Add nothing else by default: no in-app message code, no notification-click handler, and location only when the user opts in ("Ask about `OneSignalLocation`" below).
 
 ## Which SDK products
 
@@ -23,7 +23,29 @@ The documentation names 4 SPM products and the pod subspecs that match them. The
 | `OneSignalFramework` | app | yes — the SDK |
 | `OneSignalInAppMessages` | app | yes — the documentation recommends it; the module needs no code and no permission, and in-app messages sent from the dashboard render only when it is linked |
 | `OneSignalExtension` | `OneSignalNotificationServiceExtension` | yes — the NSE links it ([ios-nse.md](ios-nse.md)) |
-| `OneSignalLocation` | app | **no** — it adds location tracking and the location permission prompt. Add it only when the user's request names location; otherwise mention in the Step-8 summary, in one sentence, that it exists |
+| `OneSignalLocation` | app | **ask** — the documentation marks it optional. It shares the device's location with OneSignal and needs a location permission, so add it only when the user opts in (below) |
+
+### Ask about `OneSignalLocation` (once, before the Step-5 diff)
+
+Skip the question in 2 cases:
+
+- The user's request already says to add location (treat it as yes) or not to add it (treat it as no).
+- A prior install already links `OneSignalLocation`. Keep it and do not ask.
+
+Otherwise ask one structured question (safety contract §14) before you compute the Step-5 diff, so the one approval covers the final change set. If another question is open at that point, put both in the same tool call. Say in one sentence what the module does: OneSignal stores the device's latitude and longitude for location-based segments, after the user grants a location permission. Ask "Do you also want location tracking (the optional `OneSignalLocation` module)?" with these 2 options, in this order and with no "(Recommended)" label:
+
+1. "No, push only"
+2. "Yes, add location"
+
+**On yes**, add these 3 changes to the Step-5 change set:
+
+1. The module. SPM: the `OneSignalLocation` product on the app target, from the same package and exact version. CocoaPods: the resolver's `--line-format podfile-location` line in the app target.
+2. The usage description. Add `NSLocationWhenInUseUsageDescription` to the app's `Info.plist`; on a project that sets Info.plist keys as build settings, add `INFOPLIST_KEY_NSLocationWhenInUseUsageDescription` to Debug and Release instead. Without it, iOS never shows the location prompt and the SDK logs an error. Write one plain sentence about why the app uses location, and tell the user in Step 8 to replace it with their own words, because App Review reads it. Do not add the "Always" keys or the `location` background mode unless the user asks for background location.
+3. Location sharing. Right after `OneSignal.initialize(...)`, add `OneSignal.Location.isShared = true // onesignal:managed v1`. The SDK defaults sharing to off, so without this line the module collects nothing.
+
+Do not call `OneSignal.Location.requestPermission()` at launch: the push request in the verification helper stays the only prompt the setup adds. In the Step-8 summary, name the 2 documented ways to ask for the location permission: a location prompt in an in-app message (no code; `OneSignalInAppMessages` is already linked), or `OneSignal.Location.requestPermission()` at a moment the app chooses.
+
+**On no**, add one sentence to the Step-8 summary: location is an optional module, and a new setup run can add it.
 
 ## Dependency
 
@@ -33,15 +55,16 @@ Detect the existing manager: `Podfile`/`Podfile.lock` → CocoaPods; `Package.sw
 python3 <plugin>/scripts/resolve_sdk_version.py ios --format json   # for the version
 python3 <plugin>/scripts/resolve_sdk_version.py ios --format line --line-format podfile       # app target Podfile lines
 python3 <plugin>/scripts/resolve_sdk_version.py ios --format line --line-format podfile-nse   # NSE target Podfile line
+python3 <plugin>/scripts/resolve_sdk_version.py ios --format line --line-format podfile-location   # app target, only on a location opt-in
 ```
 
 The feed entry is the `OneSignal-iOS-SDK` repository; the SPM package is `OneSignal-XCFramework`, which publishes the same version tags, so the resolver's `version` is the pin for both (the script says so in its `note`).
 
-**Swift Package Manager:** add the package `https://github.com/OneSignal/OneSignal-XCFramework` — **not** `OneSignal-iOS-SDK`, which is the source repository and makes Xcode build the whole SDK — with an **Exact Version** rule set to the resolver's `version`. Map the products per "Which SDK products" above: `OneSignalFramework` and `OneSignalInAppMessages` on the app target, `OneSignalExtension` on the `OneSignalNotificationServiceExtension` target. The most common install mistake is a product on the wrong target: `No such module 'OneSignalFramework'` means the app target lacks it; `No such module 'OneSignalExtension'` means the NSE target lacks it. SPM add is a pbxproj edit (`XCRemoteSwiftPackageReference` + one `XCSwiftPackageProductDependency` per product) — if you cannot edit the package references safely, give the human the exact File ▸ Add Package Dependencies steps with the URL, the version, and the product-to-target table.
+**Swift Package Manager:** add the package `https://github.com/OneSignal/OneSignal-XCFramework` — **not** `OneSignal-iOS-SDK`, which is the source repository and makes Xcode build the whole SDK — with an **Exact Version** rule set to the resolver's `version`. Map the products per "Which SDK products" above: `OneSignalFramework` and `OneSignalInAppMessages` on the app target (plus `OneSignalLocation` on a location opt-in), `OneSignalExtension` on the `OneSignalNotificationServiceExtension` target. The most common install mistake is a product on the wrong target: `No such module 'OneSignalFramework'` means the app target lacks it; `No such module 'OneSignalExtension'` means the NSE target lacks it. SPM add is a pbxproj edit (`XCRemoteSwiftPackageReference` + one `XCSwiftPackageProductDependency` per product) — if you cannot edit the package references safely, give the human the exact File ▸ Add Package Dependencies steps with the URL, the version, and the product-to-target table.
 
 **CLI builds + SPM keychain wall:** `xcodebuild`-driven SPM resolution can pop a macOS **login-keychain password prompt** (and re-prompt on Deny), which stalls headless/agent runs. Pass `-scmProvider system` to `xcodebuild` so package fetching uses system git credentials instead of Xcode's keychain-backed SCM.
 
-**CocoaPods** (`Podfile`) — paste the resolver's `--line-format podfile` output verbatim into the app target and the `--line-format podfile-nse` output into the NSE target (both are exact pins), then `pod repo update && pod install`, and build the `.xcworkspace`. Shape:
+**CocoaPods** (`Podfile`) — paste the resolver's `--line-format podfile` output verbatim into the app target and the `--line-format podfile-nse` output into the NSE target (both are exact pins; on a location opt-in, also the `--line-format podfile-location` line into the app target), then `pod repo update && pod install`, and build the `.xcworkspace`. Shape:
 ```ruby
 target 'YourApp' do
   pod 'OneSignal/OneSignal', 'X.Y.Z' # onesignal:managed v1
@@ -96,7 +119,7 @@ Use the verified template [assets/ios/OneSignalSetupVerification.swift.tmpl](ass
 - register with `OneSignal.User.pushSubscription.addObserver(self)`; also read `OneSignal.User.pushSubscription.id` immediately (race guard).
 - `requestPermission` on iOS DOES take a completion block: `OneSignal.Notifications.requestPermission({ accepted in ... }, fallbackToSettings: false)` (unlike Android's suspend form).
 
-The Step-8 structural self-check (`verify_integration.py --platform ios`) enforces `#if DEBUG`, the real push observer (not NotificationCenter), init in a launch context, the NSE target with `OneSignalExtension` linked, and one App Group shared by the app and extension entitlements. Non-negotiable properties (SKILL.md Step 6):
+The Step-8 structural self-check (`verify_integration.py --platform ios`) enforces `#if DEBUG`, the real push observer (not NotificationCenter), init in a launch context, the NSE target with `OneSignalExtension` linked, one App Group shared by the app and extension entitlements, and, when `OneSignalLocation` is linked, a location usage description. Non-negotiable properties (SKILL.md Step 6):
 - Guard on `#if DEBUG` so it never ships.
 - `OneSignal.Notifications.requestPermission(..., fallbackToSettings: false)` at install — the ONLY permission prompt. `fallbackToSettings` stays `false`: the call runs at launch with no user gesture, and `true` would send a previously-denied user to the Settings app on every debug start.
 - Register the observer AND call `evaluate(OneSignal.User.pushSubscription.id)` immediately (race guard).

From 72945a1853de041c37fc4f1783e2070716d6a62c Mon Sep 17 00:00:00 2001
From: sherwinski <sherwin@onesignal.com>
Date: Wed, 28 Oct 2026 18:35:16 -0700
Subject: [PATCH 4/6] fix: scope the iOS NSE checks to the extension target

The link check now reads only the NSE target: its packageProductDependencies on SPM, or its target block in the Podfile. A OneSignal product on the app target no longer passes it. The service check needs the didReceiveNotificationExtensionRequest call, and a new warn check reports a missing OneSignalInAppMessages link.
---
 scripts/verify_integration.py | 102 +++++++++++++++++++++++++++++++---
 1 file changed, 93 insertions(+), 9 deletions(-)

diff --git a/scripts/verify_integration.py b/scripts/verify_integration.py
index 513bd41..65ecad7 100755
--- a/scripts/verify_integration.py
+++ b/scripts/verify_integration.py
@@ -111,6 +111,73 @@ def spm_range_hits(root, files=None):
     return hits
 
 
+NSE_TARGET = "OneSignalNotificationServiceExtension"
+# A pod line that links OneSignalExtension. The bare pod installs OneSignalComplete.
+_NSE_POD = re.compile(r"pod\s+['\"]OneSignal(?:XCFramework)?"
+                      r"(?:/(?:OneSignal|OneSignalExtension|OneSignalComplete))?['\"]")
+_PBX_OBJECT = re.compile(r"^\s*(\w+)\s*(?:/\*.*?\*/\s*)?=\s*\{", re.M)
+_RUBY_BLOCK_OPEN = re.compile(r"\bdo\b(\s*\|[^|]*\|)?\s*$|^\s*(if|unless|case|begin|while|until)\b")
+
+
+def podfile_target_block(text, name):
+    """Return the body of `target '<name>' do ... end` in a Podfile, or None."""
+    lines = text.splitlines()
+    start = re.compile(r"^\s*target\s+['\"]%s['\"]\s+do\b" % re.escape(name))
+    for i, line in enumerate(lines):
+        if not start.search(line):
+            continue
+        depth, body = 1, []
+        for inner in lines[i + 1:]:
+            code = inner.split("#", 1)[0]
+            if _RUBY_BLOCK_OPEN.search(code):
+                depth += 1
+            elif re.match(r"^\s*end\b", code):
+                depth -= 1
+                if depth == 0:
+                    break
+            body.append(inner)
+        return "\n".join(body)
+    return None
+
+
+def pbx_objects(text):
+    """Map each `ID = { ... }` entry in a project.pbxproj to the texts inside its
+    braces. A balanced-brace scan, no full plist parser. An ID can occur more than
+    once (PBXProject's TargetAttributes reuses each target ID as a key)."""
+    objects = {}
+    for m in _PBX_OBJECT.finditer(text):
+        depth, end = 0, m.end() - 1
+        for end in range(m.end() - 1, len(text)):
+            if text[end] == "{":
+                depth += 1
+            elif text[end] == "}":
+                depth -= 1
+                if depth == 0:
+                    break
+        objects.setdefault(m.group(1), []).append(text[m.end():end])
+    return objects
+
+
+def pbx_nse_links_extension(text):
+    """True when the NSE native target lists a package product dependency whose
+    productName is OneSignalExtension. A product on the app target does not count."""
+    objects = pbx_objects(text)
+    for body in (b for bodies in objects.values() for b in bodies):
+        # Read only the object's own keys: the `objects = { ... }` container
+        # holds every target, so nested braces must not count.
+        prev = None
+        while prev != body:
+            prev, body = body, re.sub(r"\{[^{}]*\}", "", body)
+        if not (re.search(r"isa\s*=\s*PBXNativeTarget\s*;", body)
+                and re.search(r"\bname\s*=\s*\"?%s\"?\s*;" % NSE_TARGET, body)):
+            continue
+        deps = re.search(r"packageProductDependencies\s*=\s*\(([^)]*)\)", body)
+        for ref in re.findall(r"(\w+)\s*/\*", deps.group(1)) if deps else []:
+            if any(re.search(r"productName\s*=\s*\"?OneSignalExtension\"?\s*;", b) for b in objects.get(ref, [])):
+                return True
+    return False
+
+
 _PBX_REPO_URL = re.compile(r"repositoryURL\s*=\s*\"?([^\";\n]+)")
 _PBX_REQ_KIND = re.compile(r"kind\s*=\s*(\w+)")
 
@@ -391,21 +458,24 @@ def ios_nse_present(self):
         # The Notification Service Extension is part of the default native install
         # (ios.md): without it, images, badges, and confirmed delivery fail silently
         # while plain pushes still arrive, so nothing else in this check catches it.
-        manifests = [fp for fp in walk_files(self.root)
-                     if os.path.basename(fp) in ("project.pbxproj", "Podfile")]
-        blob = "\n".join(read(fp) for fp in manifests)
-        target = "OneSignalNotificationServiceExtension" in blob
-        linked = re.search(r"productName\s*=\s*OneSignalExtension|pod\s+['\"]OneSignal", blob) is not None
+        pbx = [fp for fp in walk_files(self.root) if os.path.basename(fp) == "project.pbxproj"]
+        pods = [fp for fp in walk_files(self.root) if os.path.basename(fp) == "Podfile"]
+        target = any(NSE_TARGET in read(fp) for fp in pbx + pods)
+        linked = (any(pbx_nse_links_extension(read(fp)) for fp in pbx)
+                  or any(_NSE_POD.search(podfile_target_block(read(fp), NSE_TARGET) or "") for fp in pods))
         service = [fp for fp in walk_files(self.root)
                    if os.path.basename(fp) in ("NotificationService.swift", "NotificationService.m")
-                   and "OneSignalExtension" in read(fp)]
+                   and "OneSignalExtension" in read(fp)
+                   and "didReceiveNotificationExtensionRequest" in read(fp)]
         missing = []
         if not target:
             missing.append("no OneSignalNotificationServiceExtension target in project.pbxproj or Podfile")
         if not service:
-            missing.append("no NotificationService.swift/.m that forwards to OneSignalExtension")
+            missing.append("no NotificationService.swift/.m that calls "
+                           "OneSignalExtension.didReceiveNotificationExtensionRequest")
         if not linked:
-            missing.append("OneSignalExtension (SPM) or the OneSignal pod is not linked to the extension")
+            missing.append("the extension target does not link OneSignalExtension (SPM) or a OneSignal pod "
+                           "inside its Podfile target block")
         self.add("ios_nse_present", not missing, "warn",
                  "" if not missing else "; ".join(missing) + " (ios-nse.md)")
 
@@ -436,6 +506,19 @@ def ios_app_group_matches(self):
                  "" if ok else "the App Group differs between the app (%s) and the extension (%s); "
                  "both must name the same group" % (", ".join(sorted(app_groups)), ", ".join(sorted(nse_groups))))
 
+    def ios_in_app_messages_linked(self):
+        # The default install links OneSignalInAppMessages (ios.md); in-app
+        # messages sent from the dashboard render only when the module is linked.
+        manifests = [fp for fp in walk_files(self.root)
+                     if os.path.basename(fp) in ("project.pbxproj", "Podfile")]
+        blob = "\n".join(read(fp) for fp in manifests)
+        linked = re.search(r"productName\s*=\s*\"?OneSignalInAppMessages\"?\s*;"
+                           r"|pod\s+['\"]OneSignal(?:XCFramework)?(?:/(?:OneSignalInAppMessages|OneSignalComplete))?['\"]",
+                           blob) is not None
+        self.add("ios_in_app_messages_linked", linked, "warn",
+                 "" if linked else "OneSignalInAppMessages is not linked; in-app messages from the dashboard "
+                 "will not render (ios.md)")
+
     def ios_location_usage_description(self):
         # With OneSignalLocation linked, iOS shows no location prompt unless the
         # app declares a usage description, so the module never gets a location.
@@ -667,7 +750,8 @@ def run(self):
             "unity": [],
             "ios": [self.ios_init_in_launch, self.ios_verification_debug_guarded,
                     self.ios_verification_uses_push_observer, self.ios_nse_present,
-                    self.ios_app_group_matches, self.ios_location_usage_description],
+                    self.ios_app_group_matches, self.ios_in_app_messages_linked,
+                    self.ios_location_usage_description],
             "expo": [self.expo_plugin_registered, self.expo_plugin_first,
                      self.rn_package_present, self.rn_init_present, self.rn_verification_dev_guarded],
             "react-native": [self.rn_package_present, self.rn_init_present, self.rn_verification_dev_guarded],

From 81b63ae69592766a9bda248df362475a8bd7d01d Mon Sep 17 00:00:00 2001
From: sherwinski <sherwin@onesignal.com>
Date: Wed, 28 Oct 2026 18:35:16 -0700
Subject: [PATCH 5/6] chore: exempt only closed code fences from the
 parent-path gate

A fence that never closes no longer exempts the rest of the file. The self-test covers the case.
---
 scripts/package_directory_bundle.py | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/scripts/package_directory_bundle.py b/scripts/package_directory_bundle.py
index 6b89d14..1fa6085 100755
--- a/scripts/package_directory_bundle.py
+++ b/scripts/package_directory_bundle.py
@@ -218,16 +218,22 @@ def fenced_code_lines(text):
     Only the parent-segment check skips these lines: a `../` inside a fence is
     content the agent writes into the user's project (a pbxproj `rpath`, for
     example), not a link the plugin resolves. Every other check still reads
-    fenced lines, because the `<plugin>/scripts/` calls live in them.
+    fenced lines, because the `<plugin>/scripts/` calls live in them. A fence
+    that never closes exempts nothing, so a stray fence cannot hide the rest of
+    the file from the check.
     """
     numbers = set()
-    in_fence = False
+    block = None
     for lineno, line in enumerate(text.splitlines(), 1):
         if line.lstrip().startswith("```"):
-            in_fence = not in_fence
+            if block is None:
+                block = []
+            else:
+                numbers.update(block)
+                block = None
             continue
-        if in_fence:
-            numbers.add(lineno)
+        if block is not None:
+            block.append(lineno)
     return numbers
 
 
@@ -676,6 +682,14 @@ def self_test(source):
         ok = expect_failure("a ../ path in prose outside a code fence", bad, os.path.join(tmp, "bad-parent-path-in-prose-work"),
                             "relative path leaves the skill folder") and ok
 
+        bad = os.path.join(tmp, "bad-parent-path-after-unclosed-fence")
+        copy_source_subset(source, bad)
+        with open(os.path.join(bad, "skills", "setup", "SKILL.md"), "a", encoding="utf-8") as handle:
+            handle.write("\n```text\nCopy the file from ../shared/template.swift.\n")
+        ok = expect_failure("a ../ path after a code fence that never closes", bad,
+                            os.path.join(tmp, "bad-parent-path-after-unclosed-fence-work"),
+                            "relative path leaves the skill folder") and ok
+
         bad = os.path.join(tmp, "bad-missing-reference")
         copy_source_subset(source, bad)
         with open(os.path.join(bad, "skills", "credentials", "SKILL.md"), "a", encoding="utf-8") as handle:

From c0067f54b859cb7ea2526024f43b2f7aade35927 Mon Sep 17 00:00:00 2001
From: sherwinski <sherwin@onesignal.com>
Date: Wed, 28 Oct 2026 18:35:17 -0700
Subject: [PATCH 6/6] fix: close the review gaps in the iOS NSE recipe

- Use one Bundle ID placeholder, __MAIN_APP_BUNDLE_ID__, in every file.
- Repair an existing NSE target instead of adding a second one.
- Add the onesignal:managed v1 marker to the 2 plist templates.
- Name the native iOS exception to minimal integration in Step 5.
- Report setup.platform_config ok only when the self-check passes the NSE and App Group rows.
- Make the objectVersion = 55 workaround a separate, approved edit after the pod install error.
- Build the workspace after pod install.
---
 references/telemetry-contract.md                   | 14 +++++++++-----
 scripts/resolve_sdk_version.py                     |  7 +------
 skills/setup/SKILL.md                              |  2 +-
 ...nalNotificationServiceExtension-Info.plist.tmpl |  1 +
 ...lNotificationServiceExtension.entitlements.tmpl |  1 +
 skills/setup/ios-nse.md                            | 14 +++++++++-----
 skills/setup/ios.md                                | 14 +++++++++-----
 7 files changed, 31 insertions(+), 22 deletions(-)

diff --git a/references/telemetry-contract.md b/references/telemetry-contract.md
index dd9fcab..daade2b 100644
--- a/references/telemetry-contract.md
+++ b/references/telemetry-contract.md
@@ -76,9 +76,12 @@ verification helper both exist, because the prerequisites span both steps:
   `remote-notification`, the `aps-environment` entitlement, the pbxproj build settings,
   the `requestPermission` call in the verification helper, the
   `OneSignalNotificationServiceExtension` target with `OneSignalExtension` linked, and the
-  same App Group in both entitlements files. When the pbxproj format does not match and
-  the capability toggle or the NSE target creation goes to the human in Xcode, report
-  `fail capability_manual` at the hand-off and continue. Like `deferred` on the
+  same App Group in both entitlements files. `ok` needs the structural self-check
+  (`verify_integration.py --platform ios`) to pass `ios_nse_present` and
+  `ios_app_group_matches`, not only the agent's own reading of the edits. When the
+  pbxproj format does not match and the capability toggle or the NSE target creation
+  goes to the human in Xcode, or when one of those 2 rows still fails after a repair,
+  report `fail capability_manual` at the hand-off and continue. Like `deferred` on the
   credentials gate, this records a drop out of agent automation, not a skill stop.
 - `android` — the permission state: `INTERNET` present in the manifest, no manual
   `POST_NOTIFICATIONS` line (the SDK manifest-merges it), and the `requestPermission`
@@ -198,8 +201,9 @@ correct code that does not compile until the app module declares one more thing.
 
 `capability_manual`: the iOS pbxproj edits could not apply safely, so the Push
 Notifications and Background Modes toggles, or the creation of the Notification Service
-Extension target, went to the human in Xcode. The run cannot observe when the human
-completes them, so the milestone records the hand-off itself.
+Extension target, went to the human in Xcode. The same class covers an edit that applied
+but still fails the extension or App Group row of the self-check after a repair. The run
+cannot observe when the human completes them, so the milestone records the hand-off itself.
 
 `worker_scope_conflict`: the site already registers a service worker at the scope
 OneSignal needs. `setup.platform_config` reports the resolved conflict — the combine or
diff --git a/scripts/resolve_sdk_version.py b/scripts/resolve_sdk_version.py
index 39a1d15..85ba45b 100755
--- a/scripts/resolve_sdk_version.py
+++ b/scripts/resolve_sdk_version.py
@@ -43,12 +43,7 @@
         },
         "default_line": "gradle-kts",
     },
-    # The feed entry is the OneSignal-iOS-SDK repository. The SPM package lives in
-    # OneSignal-XCFramework, which publishes the same version tags, so the pin
-    # applies to both. The app target takes OneSignalFramework and
-    # OneSignalInAppMessages; the Notification Service Extension target takes
-    # OneSignalExtension; OneSignalLocation is added to the app target only when
-    # the user opts in.
+    # OneSignalLocation is opt-in, so only podfile-location names it.
     "ios": {
         "feed": "iOS",
         "coordinate": "OneSignal-XCFramework (SPM) / OneSignal (CocoaPods)",
diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md
index 5ba0fe0..7f89736 100644
--- a/skills/setup/SKILL.md
+++ b/skills/setup/SKILL.md
@@ -303,7 +303,7 @@ Touching anything outside this list requires re-confirming with the user. Then c
 
 **Checkpoint:** after the change set is applied, `setup.install_applied ok`. If the user rejected the diff, `fail diff_rejected` and stop. If you had to change something outside the minimal integration to make it work, use `ok_after_fix` with the registered class: `minsdk_floor` (raised `minSdk`), `kotlin_stdlib_floor`, `agp_floor` (bumped AGP), `dependency_conflict`, `manifest_merger`, `buildconfig_disabled`. Classes come from the contract's list — never invent one at the call site.
 
-Match the repo's existing architecture, style, and package manager. No repo-wide reformatting, no import reordering, no unrelated dependency bumps (safety contract §7). Minimal integration only: SDK init in the correct lifecycle spot plus what the verification helper needs — **no** extra OneSignal features unless the user asked (safety contract §8).
+Match the repo's existing architecture, style, and package manager. No repo-wide reformatting, no import reordering, no unrelated dependency bumps (safety contract §7). Minimal integration only: SDK init in the correct lifecycle spot plus what the verification helper needs — **no** extra OneSignal features unless the user asked (safety contract §8). Native iOS is the exception that §8 names: its minimal integration also includes the Notification Service Extension, the App Group, and `OneSignalInAppMessages`, so put them in the diff ([ios.md](ios.md)).
 
 ### Centralized wrapper (all platforms)
 
diff --git a/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl b/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl
index ca3cd8f..d430483 100644
--- a/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl
+++ b/skills/setup/assets/ios/OneSignalNotificationServiceExtension-Info.plist.tmpl
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!-- onesignal:managed v1 -->
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
diff --git a/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl b/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl
index 0c83383..1bc1285 100644
--- a/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl
+++ b/skills/setup/assets/ios/OneSignalNotificationServiceExtension.entitlements.tmpl
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!-- onesignal:managed v1 -->
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
diff --git a/skills/setup/ios-nse.md b/skills/setup/ios-nse.md
index 5880a02..77d747f 100644
--- a/skills/setup/ios-nse.md
+++ b/skills/setup/ios-nse.md
@@ -6,7 +6,7 @@ Reference for the `setup` skill, loaded from [ios.md](ios.md). The Notification
 
 - The `OneSignalNotificationServiceExtension` target exists and builds.
 - The NSE target links `OneSignalExtension` (SPM) or the `OneSignal/OneSignal` pod (CocoaPods).
-- The App Group `group.<MAIN_APP_BUNDLE_ID>.onesignal` is in the entitlements of **both** the main app target and the NSE target, with the same string.
+- The App Group `group.__MAIN_APP_BUNDLE_ID__.onesignal` is in the entitlements of **both** the main app target and the NSE target, with the same string.
 - The NSE deployment target equals the main app target's.
 - `NotificationService` forwards to `OneSignalExtension.didReceiveNotificationExtensionRequest`.
 - The main app embeds the `.appex` in an `Embed Foundation Extensions` build phase.
@@ -37,7 +37,7 @@ Add the same App Group to the **main app** `.entitlements`, next to `aps-environ
 ```xml
 <key>com.apple.security.application-groups</key>
 <array>
-	<string>group.MAIN_APP_BUNDLE_ID.onesignal</string>
+	<string>group.__MAIN_APP_BUNDLE_ID__.onesignal</string>
 </array>
 ```
 
@@ -45,7 +45,11 @@ Add the same App Group to the **main app** `.entitlements`, next to `aps-environ
 
 Prefer the text edit: the user's host usually has no Xcode UI, and the objects below are what File ▸ New ▸ Target writes. Preview them in the Step-5 diff like every other pbxproj edit (safety contract §5). If the pbxproj format does not match the shapes below, stop the edit and hand the target creation to the human (File ▸ New ▸ Target ▸ Notification Service Extension, named `OneSignalNotificationServiceExtension`); then still write the 3 files, the App Group, and the product link, and report `setup.platform_config fail capability_manual` ([ios.md](ios.md) → Checkpoint).
 
-Every object needs a unique 24-character hex ID. The placeholders `NSE0000000000000000000X` below stand for IDs you generate; check that none collides with an existing ID. Replace `MAIN_APP_BUNDLE_ID`, `<PROJECT_OBJECT_ID>`, and the deployment target with the project's values.
+Every object needs a unique 24-character hex ID. The placeholders `NSE0000000000000000000X` below stand for IDs you generate; check that none collides with an existing ID. Replace `__MAIN_APP_BUNDLE_ID__` (the main app target's Bundle ID, the same value as in the entitlements template), `<PROJECT_OBJECT_ID>`, and the deployment target with the project's values. No placeholder may remain in a written file.
+
+### 0. Check for an existing target first
+
+pbxproj objects cannot hold the `onesignal:managed v1` marker, so a second run cannot find its own objects by the marker. Before you add anything, search `project.pbxproj` for a `PBXNativeTarget` whose `name` is `OneSignalNotificationServiceExtension` (or any target with `productType = "com.apple.product-type.app-extension"` that already has a `NotificationService` class calling `OneSignalExtension`). If one exists, do not add the objects below (safety contract §2): repair the existing target instead. Compare it with the "Required outcomes" list, and put only the missing parts in the Step-5 diff (the product link, the App Group, the embed phase, or the 3 files).
 
 ### 1. Product reference
 
@@ -147,7 +151,7 @@ NSE00000000000000000010 /* Debug */ = {
 			"@executable_path/../../Frameworks",
 		);
 		MARKETING_VERSION = 1.0;
-		PRODUCT_BUNDLE_IDENTIFIER = MAIN_APP_BUNDLE_ID.OneSignalNotificationServiceExtension;
+		PRODUCT_BUNDLE_IDENTIFIER = __MAIN_APP_BUNDLE_ID__.OneSignalNotificationServiceExtension;
 		PRODUCT_NAME = "$(TARGET_NAME)";
 		SKIP_INSTALL = YES;
 		SWIFT_EMIT_LOC_STRINGS = YES;
@@ -223,7 +227,7 @@ end
 
 ### 7. Check the edit
 
-Run `xcodebuild -list -project <App>.xcodeproj`. A malformed pbxproj fails at once; a good one lists both targets. Then build with `-scmProvider system` ([ios.md](ios.md)): no `No such module 'OneSignalExtension'`, and the built app has `PlugIns/OneSignalNotificationServiceExtension.appex`. Keep code signing on: a build with signing disabled drops `aps-environment` and the App Group from the binary, and the SDK then reports the Push capability as missing.
+Run `xcodebuild -list -project <App>.xcodeproj`. A malformed pbxproj fails at once; a good one lists both targets. Then build with `-scmProvider system` ([ios.md](ios.md)); on a CocoaPods project, build the workspace that `pod install` writes (`-workspace <App>.xcworkspace -scheme <App>`), because a `-project` build does not link the pods: no `No such module 'OneSignalExtension'`, and the built app has `PlugIns/OneSignalNotificationServiceExtension.appex`. Keep code signing on: a build with signing disabled drops `aps-environment` and the App Group from the binary, and the SDK then reports the Push capability as missing.
 
 ## Troubleshooting
 
diff --git a/skills/setup/ios.md b/skills/setup/ios.md
index 94ec29e..237db19 100644
--- a/skills/setup/ios.md
+++ b/skills/setup/ios.md
@@ -75,7 +75,7 @@ target 'OneSignalNotificationServiceExtension' do
   pod 'OneSignal/OneSignal', 'X.Y.Z' # onesignal:managed v1
 end
 ```
-The `OneSignal` pod vendors the same XCFrameworks as the SPM package, so CocoaPods needs no repository change. CocoaPods 1.16.2+ is required; on an Xcode 16 project, `Unable to find compatibility version string for object version '70'` means the `xcodeproj` gem is too old — the documented workaround is to set `objectVersion = 55;` in the pbxproj before `pod install`.
+The `OneSignal` pod vendors the same XCFrameworks as the SPM package, so CocoaPods needs no repository change. CocoaPods 1.16.2+ is required. Do not change `objectVersion` by default. Only when `pod install` fails with `Unable to find compatibility version string for object version '70'` (the `xcodeproj` gem is too old for an Xcode 16 project), the documented workaround is `objectVersion = 55;` in the pbxproj. That line downgrades the project file format, so it is a new edit: first suggest a CocoaPods update (`gem update cocoapods` or `bundle update cocoapods`). If the user cannot update, show the one-line change as its own diff, name the revert (set `objectVersion` back to `70`), and ask for approval before you write it and run `pod install` again.
 
 ## Initialize at launch
 
@@ -102,7 +102,7 @@ SwiftUI `@main` app with no AppDelegate: call the same two lines from the `App`'
    ```
 3. For Xcode 16+ file-system-synchronized projects (`PBXFileSystemSynchronizedRootGroup`), add a `PBXFileSystemSynchronizedBuildFileExceptionSet` excluding `Info.plist` from the resource copy phase to avoid "Multiple commands produce Info.plist". Skip step 3 for classic `PBXGroup`/`PBXFileReference` projects. The `PBXFileSystemSynchronizedBuildFileExceptionSet` shape is the one in [ios-nse.md](ios-nse.md) step 3, with the app target and `Info.plist` in place of the extension's values; pbxproj edits are fragile, so preview them precisely in the diff (safety contract §5) and if the format doesn't match, hand the capability toggle to the human via Xcode's Signing & Capabilities tab instead.
 
-Add `aps-environment` to the `.entitlements` file (`development`, or `production` for release), and the App Group `group.<MAIN_APP_BUNDLE_ID>.onesignal` next to it ([ios-nse.md](ios-nse.md) → "App Group rules"). If the target has no `CODE_SIGN_ENTITLEMENTS` setting yet, add it to the Debug and Release configurations, and on an Xcode 16+ synchronized project list the entitlements file in the same `membershipExceptions` as `Info.plist`. Deployment target iOS 12.0+; do not change it if already set.
+Add `aps-environment` to the `.entitlements` file (`development`, or `production` for release), and the App Group `group.__MAIN_APP_BUNDLE_ID__.onesignal` next to it ([ios-nse.md](ios-nse.md) → "App Group rules"). If the target has no `CODE_SIGN_ENTITLEMENTS` setting yet, add it to the Debug and Release configurations, and on an Xcode 16+ synchronized project list the entitlements file in the same `membershipExceptions` as `Info.plist`. Deployment target iOS 12.0+; do not change it if already set.
 
 ## Notification Service Extension + App Group
 
@@ -119,7 +119,7 @@ Use the verified template [assets/ios/OneSignalSetupVerification.swift.tmpl](ass
 - register with `OneSignal.User.pushSubscription.addObserver(self)`; also read `OneSignal.User.pushSubscription.id` immediately (race guard).
 - `requestPermission` on iOS DOES take a completion block: `OneSignal.Notifications.requestPermission({ accepted in ... }, fallbackToSettings: false)` (unlike Android's suspend form).
 
-The Step-8 structural self-check (`verify_integration.py --platform ios`) enforces `#if DEBUG`, the real push observer (not NotificationCenter), init in a launch context, the NSE target with `OneSignalExtension` linked, one App Group shared by the app and extension entitlements, and, when `OneSignalLocation` is linked, a location usage description. Non-negotiable properties (SKILL.md Step 6):
+The Step-8 structural self-check (`verify_integration.py --platform ios`) fails the run on a missing `#if DEBUG` guard, a NotificationCenter observer in place of the real push observer, or 2 different App Groups in the app and extension entitlements. It reports, as warnings only, init outside a launch context, a missing NSE target or `OneSignalExtension` link, a missing App Group, a missing `OneSignalInAppMessages` link, and, when `OneSignalLocation` is linked, a missing location usage description. Fix every warning the iOS install should have prevented. Properties the helper must have (SKILL.md Step 6):
 - Guard on `#if DEBUG` so it never ships.
 - `OneSignal.Notifications.requestPermission(..., fallbackToSettings: false)` at install — the ONLY permission prompt. `fallbackToSettings` stays `false`: the call runs at launch with no user gesture, and `true` would send a previously-denied user to the Settings app on every debug start.
 - Register the observer AND call `evaluate(OneSignal.User.pushSubscription.id)` immediately (race guard).
@@ -137,10 +137,14 @@ apply, consent included). Run exactly one of:
 - All 6 prerequisites are in place — `UIBackgroundModes` `remote-notification`, the
   `aps-environment` entitlement, the pbxproj build settings, the `requestPermission`
   call in the helper, the `OneSignalNotificationServiceExtension` target with
-  `OneSignalExtension` linked, and the same App Group in both entitlements files:
+  `OneSignalExtension` linked, and the same App Group in both entitlements files. Do not
+  decide the last 2 from your own reading: run the Step-8 self-check
+  (`verify_integration.py --platform ios`) first, and both `ios_nse_present` and
+  `ios_app_group_matches` must pass:
   `bash <plugin>/scripts/checkpoint.sh setup.platform_config ok`
 - The pbxproj format did not match and you handed the capability toggles or the NSE
-  target creation to the human in Xcode:
+  target creation to the human in Xcode, or one of those 2 rows still fails after you
+  repair it:
   `bash <plugin>/scripts/checkpoint.sh setup.platform_config fail capability_manual`
   — report it at the hand-off and continue; the fail row records the drop out of agent
   automation, not a skill stop.