docs(ios-spm): fix stale cross-refs, document Crashlytics/SPM and shape-check gaps

Point the "Release launch dyld failure" citations in verify-ios-release-archive.sh
and tests_e2e_ios.yml at the actual "Runtime framework embedding" section (the
heading was renamed without updating callers). Document firebase_spm_shape_test.rb
in the app tests README, add the Crashlytics dSYM-under-SPM behavior and the
missing archive-signature/FIRApp-link/stale-SPM-core troubleshooting entries to
the consumer and OKF docs, and list configure-ios-dep-resolution.sh in the iOS CI
helper scripts table.

Author: russellwheatley

.github/workflows/scripts/verify-ios-release-archive.sh

@@ -14,7 +14,7 @@
 # https://github.com/invertase/react-native-firebase/pull/8933#issuecomment-4308578826
 # and the release+SPM dyld launch failure fixed by
 # packages/app/firebase_spm.rb's embed phase (see
-# okf-bundle/ios-spm-native-imports.md "Release launch dyld failure"), which
+# okf-bundle/ios-spm-native-imports.md "Runtime framework embedding"), which
 # was itself only ever validated against a Release-iphonesimulator build.
 #
 # This script does not require a signing identity or provisioning profile --

.github/workflows/tests_e2e_ios.yml

@@ -576,7 +576,7 @@ jobs:
   # repo. This job produces a real, unsigned device archive (no signing
   # identity/provisioning profile needed) and verifies the resulting app
   # bundle is actually loadable. See .github/workflows/scripts/verify-ios-release-archive.sh
-  # and okf-bundle/ios-spm-native-imports.md "Release launch dyld failure".
+  # and okf-bundle/ios-spm-native-imports.md "Runtime framework embedding".
   ios-release-archive:
     name: iOS Release Archive (${{ matrix.dep-resolution }})
     runs-on: macos-26

.spellcheck.dict.txt

@@ -310,4 +310,6 @@ SPM
 SPM-only
 TestFlight
 tvOS
+xcframework
+xcframeworks
 YAML

docs/ios-spm.mdx

@@ -183,6 +183,29 @@ uses SPM, it does not fall back to CocoaPods.
   or continue with the automatic CocoaPods fallback.
 - **SPM and CocoaPods both produce the same Firebase framework:** Remove manually
   declared Firebase pods/packages so RNFB owns Firebase dependency resolution.
+- **Release archive fails with an `xcframework-ios.signature` "couldn't be
+  copied ... because an item with the same name already exists" error:** a
+  long-standing Xcode Archive bug with SPM binary xcframeworks, not an RNFB
+  regression. RNFB works around it automatically; if the warning says it could
+  not do so, add a Run Script build phase to your app target that removes the
+  named artifact:
+
+  ```bash
+  rm -f "${CONFIGURATION_BUILD_DIR}"/<NameFromTheErrorMessage>.xcframework-ios.signature
+  ```
+
+- **Archive fails with `Undefined symbols ... _OBJC_CLASS_$_FIRApp`:** RNFB
+  links `FirebaseCore` into your app target automatically so the required
+  `[FIRApp configure]`/`FirebaseApp.configure()` call links. This only
+  surfaces if that automatic step could not run; call
+  `rnfirebase_add_spm_core_to_app_target(installer)` in your `post_install`
+  block as a fallback if your own native code also calls Firebase APIs
+  directly.
+- **A stale "firebase-ios-sdk" Swift Package reference remains on the app
+  target after switching from SPM to `$RNFirebaseDisableSPM = true`:** RNFB
+  removes it automatically on the next `pod install`; if that could not run,
+  remove the "firebase-ios-sdk" Swift Package dependency from the app target
+  manually in Xcode.
 
 After changing dependency resolution, verify both a Debug build and a Release
 archive. A simulator build alone does not exercise all framework-embedding and

okf-bundle/ci-workflows/ios.md

@@ -525,6 +525,7 @@ from this job is a known Xcode Archive bug, not a regression — see
 | `.github/workflows/scripts/wait-for-load-settle.sh` | `RNFB_LOAD_SETTLE_MAX_LOAD` (default **20**), `RNFB_LOAD_SETTLE_MAX_WAIT_SEC`, `RNFB_LOAD_SETTLE_POLL_SEC` | Poll host load immediately before Detox |
 | `.github/workflows/scripts/resource-monitor.sh` | `RNFB_RESOURCE_MONITOR_INTERVAL_SEC` (default 10), `RNFB_RESOURCE_MONITOR_LOG` | Background `uptime` + `ps` snapshots during Detox |
 | `.github/workflows/scripts/flake-summary.sh` | `RNFB_DETOX_LOG`, `RNFB_FLAKE_SUMMARY_OUT` | Post-run `rg` digest → `flake-summary.txt` |
+| `.github/workflows/scripts/configure-ios-dep-resolution.sh <spm\|cocoapods> [podfile-dir]` | — | Grep-verified `tests/ios/Podfile` patch for the `dep-resolution` matrix leg; shared by the `ios` job and `ios-release-archive` job so they can't drift apart |
 
 Detox steps use `tee detox-step.log` and `exit ${PIPESTATUS[0]}` so the artifact preserves full output while the step still fails correctly.
 

okf-bundle/ios-spm-native-imports.md

@@ -135,6 +135,22 @@ Firebase's component runtime, so they were moved to a private class extension in
 `RNFBCrashlyticsInitProvider.m`. This keeps the header imported by `.mm` code
 Firebase-free without inventing a dependency on a private/transitive target.
 
+## Crashlytics dSYM upload under SPM
+
+`packages/crashlytics/ios_config.sh` (the dSYM/symbol-upload script consumers
+wire into an Xcode "Run Script" build phase) only knew two locations for
+Crashlytics' `upload-symbols`/`run` tool: `$PODS_ROOT/FirebaseCrashlytics/run`
+and a manually-vendored `FirebaseCrashlytics.framework/run`. Neither path
+exists under SPM, so symbol upload silently no-opped for SPM users.
+
+SPM checks out `upload-symbols` under
+`DerivedData/<Project>/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/upload-symbols`.
+`BUILD_DIR` is typically `.../DerivedData/<Project>/Build/Products`, so the
+script strips from `/Build` onward to reach the `SourcePackages` checkout
+root and calls that binary directly (`chmod +x` first if the checkout didn't
+preserve the executable bit). If none of the three paths resolve, the script
+warns and lists every path it checked rather than failing silently.
+
 ## Runtime framework embedding
 
 React Native's `spm_dependency` integration attaches SPM products to pod

packages/app/__tests__/README.md

@@ -8,6 +8,21 @@ Unit tests for `firebase_spm.rb` — the shared helper that declares Firebase de
 ruby __tests__/firebase_spm_test.rb
 ```
 
+### Shape-check suite (`firebase_spm_shape_test.rb`)
+
+A companion, opt-in Minitest suite — not a replacement for `firebase_spm_test.rb`. `firebase_spm_test.rb` mocks the `Xcodeproj`/`CocoaPods` classes `firebase_spm.rb` depends on (`MockAggregateTarget`, `MockInstaller`, `MockRootObject`, `MockBuildConfig`, `MockTarget`, `MockUserProject`, `MockBuildType`, etc.) so the helper's post-install logic can be unit-tested without those gems installed. A mock is only ever as accurate as the person who wrote it, and this exact PR shipped a bug of that class (`MockAggregateTarget#build_as_static?` modeled as a directly-settable flag, when the real `Pod::Target#build_as_static?` is unconditionally `true` — the actual per-install signal is `target_definition.build_type.static?`), which only surfaced via a real `pod install`.
+
+`firebase_spm_shape_test.rb` asserts, against the **real** `xcodeproj`/`cocoapods` gems, that every mocked class/method in `firebase_spm_test.rb` still has the shape those mocks assume — so a future CocoaPods/Xcodeproj release that changes that shape fails in seconds instead of ~20 minutes into a real `pod install` in the E2E jobs.
+
+It skips cleanly (no failure, no tests defined) when `xcodeproj`/`cocoapods` aren't installed, so it is always safe to run unconditionally:
+
+```bash
+ruby __tests__/firebase_spm_shape_test.rb
+```
+
+- **"Test Firebase SPM Helper" step** (`tests_jest.yml`) never installs these gems — the suite is expected to skip there.
+- **"Verify Firebase SPM Xcodeproj/CocoaPods API shape" step** (`tests_e2e_other.yml`, `other` job) does have them and runs the suite for real, right after that job's existing `gem update cocoapods xcodeproj` step — no new CI job, no new gem installs.
+
 ### What is `Pod::Specification` and why is it mocked?
 
 `Pod::Specification` is the core CocoaPods class — it's the `s` object used inside every `.podspec` file to declare things like `s.dependency`, `s.name`, `s.version`, etc. We mock it with a simple class that records `dependency` calls, so we can run the tests without installing CocoaPods.