{"owner":"firebase","repo":"firebase-ios-sdk","hasSkills":true,"totalSkillsCount":4,"totalTokensCount":7332,"categories":["root-instruction","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"firebase-ios-sdk":{"command":"npx","args":["-y","@modelcontextprotocol/server-firebase-ios-sdk"]}}},"found":["AGENTS.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"AGENTS.md":"# agents.md - Context for AI Assisted Development\n\nThis file highlights key aspects of the development environment, coding practices, and\narchitectural patterns covered in this repo. When an agents.md file is present in a product's\nsubdirectory, prefer using the workflow defined there.\n\n## Setup Commands\n\nTo contribute to or develop within the `firebase-ios-sdk` repository, an understanding of the\nfollowing setup is beneficial.\n\n### Prerequisites\n\n1.  **Xcode**: The development environment relies on Xcode 26.2 or above.\n2.  **Command-Line Tools**:\n    *   `clang-format`: Used for C, C++, and Objective-C code formatting. Version 23 is\n        specifically mentioned.\n    *   `mint`: Used to install and run Swift command-line tools, including `swiftformat` for\n        Swift code styling.\n    *   Note: The build environment uses `clang-format` (version 23) and `mint` (for\n        `swiftformat`) for code styling. Ensure any generated or modified code adheres to these\n        styling requirements.\n\n### Development Workflows\n\nYou can develop Firebase libraries using either Swift Package Manager (SPM) or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\nSwift Package Manager (SPM) is a primary development workflow. The project is typically opened\nvia the `Package.swift` file at the repository root.\n\n*   When working with SPM, specific library schemes (e.g., `FirebaseAuth`, `FirebaseFirestore`)\n    are used to build and develop individual modules.\n*   For test-related tasks using SPM, be aware of the `./scripts/setup_spm_tests.sh` script, which\n    configures Xcode to show schemes for testing individual packages. This script may need to be\n    invoked if tests need to be run or modified in an SPM context.\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n\n#### 2. CocoaPods\n\nCocoaPods (v1.12.0+) is another key development workflow.\n\n*   The `cocoapods-generate` plugin is used to create a development workspace from a `.podspec`\n    file.\n*   Development workspaces for individual libraries (e.g., `FirebaseStorage`) are generated using\n    a command like:\n    ```bash\n    pod gen FirebaseStorage.podspec --local-sources=./ --auto-open --platforms=ios\n    ```\n    *   Replace `FirebaseStorage.podspec` with the podspec of the library you intend to develop.\n        Podspecs are located in the root directory.\n    *   The `--local-sources=./` flag tells CocoaPods to use the local checkout of the SDK.\n    *   `--platforms` can be set to `ios`, `macos`, or `tvos`. Note that for Xcode 10.2+,\n        multi-platform CocoaPods workspaces might have issues, so generating for a single\n        platform is advised by `README.md`.\n    *   If the CocoaPods cache is outdated, you might need to run `pod repo update` first.\n*   Understanding this command structure is important if tasks involve setting up or modifying a\n    CocoaPods-based development environment for a specific module.\n*   **Mac Catalyst Development**:\n    1.  Run `pod gen` as above for `ios`.\n    2.  In the generated project, check the \"Mac\" box in the host app's \"Build Settings\" under\n        Deployment.\n    3.  Configure signing for the host app in \"Signing & Capabilities.\"\n    4.  In the \"Pods\" project, add signing to the host app and unit test targets.\n    5.  Alternatively, disable code signing by adding a user-defined setting\n        `CODE_SIGNING_REQUIRED` with value `NO` to each relevant target's build settings.\n\n### Code Styling\n\nCode consistency is maintained by `clang-format` (for C-based languages) and `swiftformat` (for\nSwift). Any code generated or modified must adhere to these standards.\n\n*   The `./scripts/style.sh` script is used to apply formatting. If a task involves code\n    changes, this script (or the underlying tools) should be used to ensure compliance:\n    ```bash\n    ./scripts/style.sh {path_to_changed_files_or_branch_name}\n    ```\n    For example:\n    ```bash\n    ./scripts/style.sh FirebaseStorage/Sources/\n    # OR\n    ./scripts/style.sh my-feature-branch\n    ```\n    Running `./scripts/style.sh` with no arguments will format all eligible files in the\n    repository.\n*   Failures in CI style checks often indicate that code modifications were not formatted\n    correctly with these tools.\n\n### Firestore Specific Development\n\nFirestore has a self-contained Xcode project. For details, refer to `Firestore/README.md`.\n\n## Testing\n\nThorough testing is essential for maintaining the quality and stability of the Firebase SDK.\n\n### General Guidelines\n\n*   **Write Tests**:\n    *   When fixing a bug, add a test to prevent regressions.\n    *   When adding a new feature, include tests to validate the new or modified APIs.\n*   **Tests as Documentation**: Well-written tests can serve as examples of how to use an API.\n*   **Code Coverage**: Aim for good code coverage to ensure all critical paths are tested.\n\n### Running Tests\n\nThe primary method for running tests is through Xcode, after setting up your development\nenvironment using either Swift Package Manager or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\n1.  **Enable Test Schemes**: If you haven't already, run the script from the repository root:\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n2.  **Run Tests**:\n    *   In Xcode, select the scheme corresponding to the library or test suite you want to run\n        (e.g., `FirebaseFirestoreTests`).\n    *   Choose the target platform (run destination) along with the scheme.\n    *   Press `⌘U` or click the \"play\" arrow in the project navigation bar to run the tests.\n    *   Note: `CONTRIBUTING.md` mentions that not all test schemes might be configured to run\n        with SPM.\n\n##### Environment Variables in SwiftPM\n\nThe following are environment variables to modify sources of code that can help with testing\nspecific frameworks or dealing with version mismatches.\n*   `FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT`: When passed, sets the dependency on the\n    https://github.com/google/GoogleAppMeasurement.git package to use the main branch. This is\n    done to keep the Firebase package's main branch building when it depends on unreleased changes\n    in the GoogleAppMeasurement package's main branch. Use it when you run into version issues.\n*   `FIREBASECI_USE_LOCAL_FIRESTORE_ZIP`: When passed, looks for a local\n    `FirebaseFirestoreInternal.xcframework` framework at the root of the repo to resolve the\n    Firestore target. Used for testing incombination with `scripts/check_firestore_symbols.sh`.\n*   `FIREBASE_SOURCE_FIRESTORE`: When passed, builds Firestore's large C++ dependencies (abseil,\n     gRPC, BoringSSL) from source rather than, by default, using existing binaries.\n\nTo enable an env var within Xcode, quit the current Xcode instance, and open it from the command\nline, passing each desired env var with the `--env` argument.\n```console\nopen --env FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT --env FIREBASE_SOURCE_FIRESTORE \\\nPackage.swift\n```\n\nTo unset the env vars, quit the running Xcode instance.\n\n#### 2. CocoaPods\n\n1.  **Generate Workspace**: After generating a workspace using `pod gen ...` as described in the\n    \"Setup Commands\" section.\n2.  **Run Tests**:\n    *   Open the generated `.xcworkspace`.\n    *   Select the appropriate scheme for the unit tests of the library\n        (e.g., `FirebaseStorage-Unit-unit`).\n    *   Press `⌘U` or click the \"play\" arrow to run tests.\n\n### Code Coverage\n\n*   **Enable in Xcode**:\n    1.  Go to `Product → Scheme ➞ Edit Scheme...` (or use `⌥⌘U`).\n    2.  Select the \"Test\" action in the sidebar.\n    3.  Go to the \"Options\" tab.\n    4.  Check the \"Code Coverage\" box.\n*   **Coverage Report Tool**: The repository includes a tool for generating more detailed\n    coverage reports. Refer to its documentation: `scripts/code_coverage_report/README.md`.\n\n### Handling `GoogleService-Info.plist` in Tests\n\nConfiguration files like `GoogleService-Info.plist` are necessary for Firebase SDKs to connect to\na backend project. How these are handled in tests varies:\n\n*   **Unit Tests**:\n    *   Unit tests should generally not rely on a live backend or a real\n        `GoogleService-Info.plist`.\n    *   Where configuration is needed (e.g., for `FirebaseApp.configure()`), tests often use\n        mock or fake `GoogleService-Info.plist` files with dummy values. These are typically\n        included directly in the test target's resources. Be aware of this pattern if tests\n        seem to require Firebase app initialization.\n*   **Integration Tests & Sample Apps**:\n    *   Integration tests and sample apps, which do interact with live backends, require valid\n        `GoogleService-Info.plist` files.\n    *   In the CI (Continuous Integration) environment, these files are usually provided\n        securely (e.g., via environment variables, mounted secrets, or dedicated build steps\n        that place the correct plist). As an AI agent, you typically won't manage these CI\n        secrets directly.\n    *   If integration tests fail due to configuration issues, it might relate to how the CI\n        environment provides this plist.\n    *   For local execution of sample apps or some integration tests (if specifically requested\n        for a task), a valid plist obtained from the Firebase console for a test project would\n        be needed, as described in the original `README.md`. However, direct interaction with\n        the Firebase console to download plists is outside typical AI agent operations unless\n        explicitly guided.\n\n### Product-Specific Testing Notes\n\n*   **Firebase Database**:\n    *   Integration tests can run against a local Database Emulator or a production instance.\n    *   **Emulator**: Run `./scripts/run_database_emulator.sh start` before executing tests.\n    *   **Production**: Provide a valid `GoogleService-Info.plist` (copied to\n        `FirebaseDatabase/Tests/Resources/GoogleService-Info.plist`) and ensure security rules\n        are public during the test run.\n*   **Firebase Storage**:\n    *   For integration tests, follow instructions in\n        `FirebaseStorage/Tests/Integration/StorageIntegration.swift`.\n*   **Push Notifications (General for Messaging, etc.)**:\n    *   Cannot be tested on the iOS Simulator; requires a physical device.\n    *   Requires specific App ID provisioning in the Apple Developer portal.\n    *   Upload your APNs Provider Authentication Key or certificate to the Firebase Console.\n    *   Ensure the test device is registered in your Apple Developer account.\n\n## API Surface\n\nDesigning and maintaining a consistent and developer-friendly API is critical for the Firebase\nSDK. Adherence to established guidelines is important for a good user experience and should be\nfollowed when tasks involve API modifications.\n\n### Guiding Principles for New APIs\n\nThe primary reference for API design is `docs/firebase-api-guidelines.md`. Key principles for new\nAPI designs include:\n\n*   **Swift-First**: New APIs should be designed and implemented in Swift. Objective-C APIs\n    require strong justification. Generated Swift interfaces for Objective-C APIs should be\n    manually refined for Swift idioms if necessary.\n*   **Swift Code Samples**: Swift code samples should be prioritized in API proposals and\n    documentation.\n*   **Async/Await**: New asynchronous APIs should use Swift's `async/await`. Callback-based APIs\n    require justification (though callbacks are still appropriate for event handlers).\n    ```swift\n    // Preferred\n    public func fetchData() async throws -> Data { /* ... */ }\n\n    // Pre-Swift Concurrency (No longer preferred for new async APIs)\n    public func fetchData(completion: (Data?, Error?) -> Void) { /* ... */ }\n    ```\n*   **Sendable Types**: New APIs should be `Sendable` where applicable, to allow safe use in\n    concurrent contexts (e.g., within a `Task`).\n*   **Access Control**:\n    *   `public` access level should be used for new Swift APIs rather than `open`.\n    *   New Swift classes should generally be `final` to prevent subclassing, unless subclassing\n        is an intended design feature.\n*   **API Availability**:\n    *   The `@available` attribute is used to specify platform and version compatibility (e.g.,\n        `@available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)`).\n    *   The minimum supported versions for SPM are often tied to Analytics/Crashlytics. For other\n        APIs, the product's CocoaPods podspec is the reference for versioning in `@available`.\n*   **Constants**:\n    *   Constants in Swift should be defined within case-less enums (prevents instantiation).\n    *   The \"k\" prefix for Swift constants should be avoided.\n    ```swift\n    public enum NetworkConstants {\n        public static let httpPostMethod = \"POST\"\n    }\n    ```\n*   **Minimize Optionals**: While Swift's optionals provide type safety for nullability, their\n    overuse should be avoided to prevent complicating call sites.\n*   **Structs vs. Enums for Extensibility**:\n    *   For sets of values that might expand in the future, `structs` with static factory\n        methods are preferred over `enums`. Adding a case to a public Swift enum is a breaking\n        change.\n    *   See `docs/firebase-api-guidelines.md` (links to PRs #13728, #13976) for examples.\n*   **Avoid `Any`, `AnyObject`, NS-Types**: `Any`, `AnyObject`, or Objective-C NS-prefixed types\n    (like `NSString`, `NSDictionary`) should not be used in public Swift APIs. Swift native\n    types (`String`, `Dictionary`) are preferred, and heterogeneous collections should be\n    modeled with enums or structs for type safety.\n*   **Documentation**: New APIs must be documented using Swift-flavored Markdown. Xcode's `⌥ ⌘ /`\n    shortcut can generate documentation block structure.\n*   **Naming Conventions**:\n    *   Clarity and expressiveness should be prioritized (e.g., `fetchMetadata()` over `fetch()`\n        or `getMetadata()`).\n    *   Consistency with existing Firebase APIs must be maintained.\n    *   Refer to [Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).\n*   **Error Handling**:\n    *   APIs that can fail should be marked with `throws`.\n    *   Public error types conforming to Swift's `Error` protocol should be defined and thrown.\n*   **Objective-C (If Necessary)**:\n    *   Defining `typedefs` in public Objective-C headers should be avoided as they obscure the\n        underlying type in the generated Swift interface. Full types should be used.\n\n### Header Management and Imports\n\nThe document `HeadersImports.md` provides detailed guidelines. Key points include:\n\n*   **Public Headers**:\n    *   Define the library's public API.\n    *   Located in `FirebaseFoo/Sources/Public/FirebaseFoo/`.\n    *   Additions are minor version updates; changes/deletions are major.\n*   **Public Umbrella Header**:\n    *   A single header including the library's full public API\n        (e.g., `FirebaseFoo/Sources/Public/FirebaseFoo/FirebaseFoo.h`).\n*   **Private Headers**:\n    *   Located in `FirebaseFoo/Sources/Private/`.\n    *   Available to other libraries within the `firebase-ios-sdk` repo but NOT part of the\n        public API.\n    *   For CocoaPods, these are included in `source_files`, not `private_header_files`.\n*   **Interop Headers**:\n    *   Special private headers for defining interfaces between libraries\n        (see `Interop/FirebaseComponentSystem.md`).\n*   **Private Umbrella Header**:\n    *   Includes public API + private APIs for other in-repo libraries. Package manager\n        complexities should be localized here.\n*   **Library Internal Headers**:\n    *   Only used by the enclosing library, located among its source files.\n*   **Import Styles**:\n    *   **Within the same library**: Use repo-relative paths\n        (e.g., `#import \"FirebaseFoo/Sources/Internal/MyInternalHeader.h\"`).\n        *   *Exception*: Public headers importing other public headers from the *same library*\n            should use unqualified imports (`#import \"AnotherPublicHeaderInFoo.h\"`) to avoid\n            module collisions.\n    *   **Private Headers from other libraries**: Import the private umbrella header\n        (e.g., `#import \"FirebaseCore/Extension/FirebaseCoreInternal.h\"`).\n    *   **External Dependencies**:\n        ```objectivec\n        #if SWIFT_PACKAGE\n        @import GTMSessionFetcherCore;\n        #else\n        #import <GTMSessionFetcher/GTMSessionFetcher.h>\n        #endif\n        ```\n\nThis structure ensures that APIs are well-defined, discoverable, and maintainable across\ndifferent build systems and for various Firebase products.\n\n## Best Practices\n\nAdhering to best practices ensures code quality, maintainability, and a positive developer\nexperience for both contributors and users of the Firebase SDK.\n\n*   **Contribution Guidelines**: The `CONTRIBUTING.md` file contains detailed information on the\n    development workflow, pull requests, coding styles, and environment setup, which should be\n    adhered to.\n*   **Code of Conduct**: All contributions and interactions must align with the\n    [Code of Conduct](CODE_OF_CONDUCT.md).\n*   **Swift-First Development**: New features and APIs should prioritize Swift, as outlined in the\n    API guidelines. Objective-C is used only with strong justification.\n*   **Modularity**: The SDK's modular design, with each Firebase product in its own library/pod\n    (e.g., Auth, Firestore, Storage), promotes separation of concerns. Changes should generally\n    be focused within a product's dedicated directory.\n*   **Dependency Management**:\n    *   Internal dependencies (between Firebase pods) are managed via version specifications in\n        `.podspec` files or `Package.swift`.\n    *   External dependencies are also declared here. The impact of adding new external\n        dependencies requires careful consideration.\n*   **Central FirebaseApp (`FIRApp`)**:\n    *   `FirebaseApp` (Swift) / `FIRApp` (Objective-C) is the central class for initializing and\n        configuring Firebase.\n    *   It provides access to project-level configurations from `GoogleService-Info.plist`.\n*   **Component System (`FIRComponent`)**:\n    *   An internal component system (`FIRComponent`, `FIRComponentContainer`) is used for\n        registering and discovering Firebase services at runtime.\n    *   This enables a decoupled architecture. New top-level Firebase pods often require\n        registration with this system (see `docs/AddNewPod.md` and `FIRApp.m`).\n*   **`GoogleService-Info.plist` (in relation to SDK code)**:\n    *   While handling `GoogleService-Info.plist` in tests has specific considerations (see\n        \"Handling `GoogleService-Info.plist` in Tests\"), SDK code itself relies on `FirebaseApp`\n        to provide project configurations derived from such a file.\n*   **`-ObjC` Linker Flag**:\n    *   Awareness of the `-ObjC` \"Other Linker Flags\" setting is important, as it's necessary\n        for applications using Firebase Analytics (and often transitively, other Firebase SDKs)\n        to correctly link Objective-C categories.\n*   **Changelogs**: `CHANGELOG.md` files (root and product-specific) must be updated with\n    meaningful descriptions of changes for any pull request. The changelog\n    entry should always go into a new top-level `# Unreleased` section. If this\n    section does not already exist, you must create it at the top of the file.\n*   **Minimize Breaking Changes**: Breaking changes are avoided if possible and require careful\n    consideration, typically aligning with major version releases.\n*   **Platform Support**: Different levels of support exist for Apple platforms (macOS, Catalyst,\n    tvOS, visionOS, watchOS). `@available` and conditional compilation (`#if os(iOS)`) are\n    used. visionOS and watchOS are community-supported.\n*   **Header Hygiene**: Guidelines in `HeadersImports.md` must be followed strictly for\n    compatibility.\n*   **Testing**: Comprehensive testing (unit, integration) is a core best practice. Tests must\n    cover new code and bug fixes.\n\nAdherence to these practices helps maintain the quality and robustness of the Firebase Apple\nSDKs.\n\n## Common Patterns\n\nRecognizing the following common design and implementation patterns, prevalent throughout the\nFirebase Apple SDKs, facilitates understanding the existing codebase and developing new features\nconsistently.\n\n*   **Async/Await and Sendable for Swift**:\n    *   New asynchronous Swift code predominantly uses `async/await` for cleaner, more readable\n        control flow.\n    *   Types involved in concurrent operations are increasingly expected to conform to\n        `Sendable` to ensure thread safety, especially with Swift 6's stricter concurrency\n        checking.\n*   **Case-less Enums for Constants**:\n    *   Swift code uses case-less enums to group related constants, preventing instantiation and\n        providing a clear namespace.\n    ```swift\n    public enum StorageConstants {\n        public static let maxUploadRetryTime: TimeInterval = 600.0\n        public static let defaultChunkSize: Int64 = 256 * 1024\n    }\n    ```\n*   **Structs for Extensible Enum-like Values**:\n    *   When a set of predefined values (akin to enum cases) might need to be expanded without\n        causing breaking changes, `structs` with static factory methods are often used. This\n        avoids the issue where adding a new case to a public `enum` breaks client `switch`\n        statements. (See `docs/firebase-api-guidelines.md` for context).\n*   **Protocol Buffers (Protobuf / Nanopb)**:\n    *   Several modules (e.g., Crashlytics, Firestore, InAppMessaging, Performance, Messaging)\n        utilize Protocol Buffers for data serialization.\n    *   This involves `.proto` files defining data structures and scripts\n        (e.g., `generate_protos.sh`) for compilation into Swift or Objective-C (often Nanopb\n        for C/Objective-C). Due to their complexity and impact on build processes, introducing\n        Protobufs to new areas of the SDK should be avoided unless that area already heavily\n        relies on them or it's a specific requirement for interacting with an existing\n        Protobuf-based system.\n*   **API Visibility Layers (Public/Private/Internal)**:\n    *   A clear distinction is maintained for API visibility:\n        *   **Public**: APIs intended for end-users, found in `Sources/Public/` directories.\n            Changes here are subject to semantic versioning.\n        *   **Private**: APIs intended for use by *other Firebase SDKs within this repository*\n            but not for public consumption. Often found in `Sources/Private/` or `Interop/`\n            directories.\n        *   **Internal/Project**: Code and headers used only within the same library/module.\n            These are typically co-located with the module's other source files.\n*   **Umbrella Headers**:\n    *   **Public Umbrella Header**: Each library typically has a main public header\n        (e.g., `FirebaseFoo.h`) that includes all other public headers for that library,\n        simplifying imports for Objective-C users.\n    *   **Private Umbrella Header**: Some libraries may have an internal or extension umbrella\n        header (e.g., `FirebaseCoreInternal.h`) to expose necessary private APIs to other\n        Firebase libraries.\n*   **Module-Specific Prefixes (Objective-C)**:\n    *   Objective-C class names are typically prefixed to avoid collisions (e.g., `FIR` for\n        Firebase Core, `FST` for Firestore, `FIRCLS` for Crashlytics). This is less of a concern\n        in Swift due to namespacing with module names.\n*   **Error Handling Conventions**:\n    *   Swift: Adopts the `Error` protocol, with specific error enums/structs per module.\n    *   Objective-C: Uses `NSError**` parameters and standard error domains (often\n        module-specific).\n*   **Delegate Pattern (Objective-C & Swift)**:\n    *   Commonly used for callbacks and event notifications, especially in older Objective-C APIs\n        or when multiple distinct events need to be communicated.\n*   **Completion Handlers (Callbacks)**:\n    *   While `async/await` is preferred for new Swift asynchronous operations, completion\n        handlers remain prevalent in many existing Objective-C and Swift APIs. These typically\n        take `(ResultType?, Error?)` or similar parameters.\n*   **Singletons and Shared Instances**:\n    *   Many Firebase services offer a shared instance or singleton accessor\n        (e.g., `FirebaseApp.app()`, `Firestore.firestore()`, `Auth.auth()`).\n*   **Resource Bundles**:\n    *   SDKs requiring UI components or other resources (e.g., Firebase In-App Messaging) may\n        package them into `.bundle` files.\n*   **Use of `dispatch_once` / Lazy Initialization for Singletons (Objective-C)**:\n    *   This is a common Objective-C pattern for ensuring singleton instances are initialized\n        safely and only once. Swift employs `static let` properties for a similar outcome.\n\nUnderstanding these patterns is key to navigating the codebase and contributing effectively.\n\n## External Dependencies\n\nThe Firebase Apple SDK integrates several external open-source libraries to provide its\nfunctionality. These dependencies are managed as part of the overall SDK build and release\nprocess, primarily through CocoaPods and Swift Package Manager configurations.\n\nExamples of such dependencies include (but are not limited to):\n*   gRPC (for Firestore and other components)\n*   LevelDB (for Firestore local persistence)\n*   nanopb (for Protocol Buffer serialization in C/Objective-C contexts)\n*   abseil-cpp (common C++ libraries)\n*   GTMSessionFetcher (for networking)\n\nWhen working on tasks for this repository, **do not introduce new external dependencies** unless\nexplicitly instructed to do so by the user. Adding and managing dependencies in a large SDK like\nthis involves careful consideration of binary size, licensing, potential conflicts, and long-term\nmaintenance. The existing dependencies are curated and managed by the Firebase team. If a task\nseems to require functionality that might suggest a new library, discuss alternatives or confirm\nthe need for a new dependency with the user first.\n\n## Updating agents.md\n\nThis document (`agents.md`) is intended as a living guide to assist AI agents (like Jules) in\nunderstanding and contributing to the `firebase-ios-sdk` repository. As the SDK evolves, new\npatterns may emerge, best practices might be updated, or setup procedures could change.\n\n**Guideline for Future Tasks:**\nIf, during the course of completing new tasks, you identify:\n*   New common patterns or architectural decisions.\n*   Changes to the build, test, or setup process.\n*   Updates to API design philosophies or best practices.\n*   Any other information that would be beneficial for an AI agent to have context on this\n    repository.\n\nPlease consider updating this `agents.md` file to reflect those new findings. Keeping this\ndocument current will improve the efficiency and accuracy of future AI-assisted development.\n\n## Technical Debt & Known Issues\n\n*   **Remote Config Memory & Concurrency**:\n    *   `setCustomSignals:` also strongly captures `self` via `self->_settings.customSignals`.\n    *   There is a deadlock hazard in `configValueForKey:` due to synchronous dispatch to `_queue` which then dispatches asynchronously back to `_queue` via `callListeners:`.\n    *   `RCNConfigExperiment` has data race risks on `_experimentPayloads` and other mutable collections as they are mutated from different queues (e.g., `loadExperimentFromTable` vs `updateExperimentsWithResponse:`).\n    *   In `RCNConfigExperiment`, `updateActiveExperimentsInDB` performs asynchronous DB operations. Subsequent code in `updateExperimentsWithHandler:` (such as `updateExperimentsWithServiceOrigin:`) is not guaranteed to execute after the DB updates complete, leading to a potential race condition.\n\n## AI Subagent Personas\n\nThe following personas are defined for use by AI orchestrators (like the\n`autonomous-tdd-loop` skill).\n\n### Objective Code Verifier\n**Role:** Objective Code Verifier\n**Prompt Guidelines:** Your job is strictly to run builds and test suites. Use\nthe `./scripts/style.sh` for formatting checks, and\n`./scripts/setup_spm_tests.sh` followed by `xcodebuild` (or `pod gen` and\n`xcodebuild` for CocoaPods) as dictated by the orchestrator. You are to report\na binary pass/fail result along with the specific error output if a failure\noccurs. Do not attempt to fix the code yourself unless specifically instructed.\n\n### Rigorous Code Reviewer\n**Role:** Rigorous Code Reviewer\n**Prompt Guidelines:** Your job is to perform a subjective, rigorous code\nreview on proposed changes. Focus on concurrency (Swift 6 strict concurrency),\nmemory management (retain cycles, etc.), API design (following\n`docs/firebase-api-guidelines.md`), and overall architectural consistency with\nthe rest of the Firebase iOS SDK. You should enforce best practices and flag\nany issues for the main agent to address.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/plugin.json)"},"files":{"AGENTS.md":"# agents.md - Context for AI Assisted Development\n\nThis file highlights key aspects of the development environment, coding practices, and\narchitectural patterns covered in this repo. When an agents.md file is present in a product's\nsubdirectory, prefer using the workflow defined there.\n\n## Setup Commands\n\nTo contribute to or develop within the `firebase-ios-sdk` repository, an understanding of the\nfollowing setup is beneficial.\n\n### Prerequisites\n\n1.  **Xcode**: The development environment relies on Xcode 26.2 or above.\n2.  **Command-Line Tools**:\n    *   `clang-format`: Used for C, C++, and Objective-C code formatting. Version 23 is\n        specifically mentioned.\n    *   `mint`: Used to install and run Swift command-line tools, including `swiftformat` for\n        Swift code styling.\n    *   Note: The build environment uses `clang-format` (version 23) and `mint` (for\n        `swiftformat`) for code styling. Ensure any generated or modified code adheres to these\n        styling requirements.\n\n### Development Workflows\n\nYou can develop Firebase libraries using either Swift Package Manager (SPM) or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\nSwift Package Manager (SPM) is a primary development workflow. The project is typically opened\nvia the `Package.swift` file at the repository root.\n\n*   When working with SPM, specific library schemes (e.g., `FirebaseAuth`, `FirebaseFirestore`)\n    are used to build and develop individual modules.\n*   For test-related tasks using SPM, be aware of the `./scripts/setup_spm_tests.sh` script, which\n    configures Xcode to show schemes for testing individual packages. This script may need to be\n    invoked if tests need to be run or modified in an SPM context.\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n\n#### 2. CocoaPods\n\nCocoaPods (v1.12.0+) is another key development workflow.\n\n*   The `cocoapods-generate` plugin is used to create a development workspace from a `.podspec`\n    file.\n*   Development workspaces for individual libraries (e.g., `FirebaseStorage`) are generated using\n    a command like:\n    ```bash\n    pod gen FirebaseStorage.podspec --local-sources=./ --auto-open --platforms=ios\n    ```\n    *   Replace `FirebaseStorage.podspec` with the podspec of the library you intend to develop.\n        Podspecs are located in the root directory.\n    *   The `--local-sources=./` flag tells CocoaPods to use the local checkout of the SDK.\n    *   `--platforms` can be set to `ios`, `macos`, or `tvos`. Note that for Xcode 10.2+,\n        multi-platform CocoaPods workspaces might have issues, so generating for a single\n        platform is advised by `README.md`.\n    *   If the CocoaPods cache is outdated, you might need to run `pod repo update` first.\n*   Understanding this command structure is important if tasks involve setting up or modifying a\n    CocoaPods-based development environment for a specific module.\n*   **Mac Catalyst Development**:\n    1.  Run `pod gen` as above for `ios`.\n    2.  In the generated project, check the \"Mac\" box in the host app's \"Build Settings\" under\n        Deployment.\n    3.  Configure signing for the host app in \"Signing & Capabilities.\"\n    4.  In the \"Pods\" project, add signing to the host app and unit test targets.\n    5.  Alternatively, disable code signing by adding a user-defined setting\n        `CODE_SIGNING_REQUIRED` with value `NO` to each relevant target's build settings.\n\n### Code Styling\n\nCode consistency is maintained by `clang-format` (for C-based languages) and `swiftformat` (for\nSwift). Any code generated or modified must adhere to these standards.\n\n*   The `./scripts/style.sh` script is used to apply formatting. If a task involves code\n    changes, this script (or the underlying tools) should be used to ensure compliance:\n    ```bash\n    ./scripts/style.sh {path_to_changed_files_or_branch_name}\n    ```\n    For example:\n    ```bash\n    ./scripts/style.sh FirebaseStorage/Sources/\n    # OR\n    ./scripts/style.sh my-feature-branch\n    ```\n    Running `./scripts/style.sh` with no arguments will format all eligible files in the\n    repository.\n*   Failures in CI style checks often indicate that code modifications were not formatted\n    correctly with these tools.\n\n### Firestore Specific Development\n\nFirestore has a self-contained Xcode project. For details, refer to `Firestore/README.md`.\n\n## Testing\n\nThorough testing is essential for maintaining the quality and stability of the Firebase SDK.\n\n### General Guidelines\n\n*   **Write Tests**:\n    *   When fixing a bug, add a test to prevent regressions.\n    *   When adding a new feature, include tests to validate the new or modified APIs.\n*   **Tests as Documentation**: Well-written tests can serve as examples of how to use an API.\n*   **Code Coverage**: Aim for good code coverage to ensure all critical paths are tested.\n\n### Running Tests\n\nThe primary method for running tests is through Xcode, after setting up your development\nenvironment using either Swift Package Manager or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\n1.  **Enable Test Schemes**: If you haven't already, run the script from the repository root:\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n2.  **Run Tests**:\n    *   In Xcode, select the scheme corresponding to the library or test suite you want to run\n        (e.g., `FirebaseFirestoreTests`).\n    *   Choose the target platform (run destination) along with the scheme.\n    *   Press `⌘U` or click the \"play\" arrow in the project navigation bar to run the tests.\n    *   Note: `CONTRIBUTING.md` mentions that not all test schemes might be configured to run\n        with SPM.\n\n##### Environment Variables in SwiftPM\n\nThe following are environment variables to modify sources of code that can help with testing\nspecific frameworks or dealing with version mismatches.\n*   `FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT`: When passed, sets the dependency on the\n    https://github.com/google/GoogleAppMeasurement.git package to use the main branch. This is\n    done to keep the Firebase package's main branch building when it depends on unreleased changes\n    in the GoogleAppMeasurement package's main branch. Use it when you run into version issues.\n*   `FIREBASECI_USE_LOCAL_FIRESTORE_ZIP`: When passed, looks for a local\n    `FirebaseFirestoreInternal.xcframework` framework at the root of the repo to resolve the\n    Firestore target. Used for testing incombination with `scripts/check_firestore_symbols.sh`.\n*   `FIREBASE_SOURCE_FIRESTORE`: When passed, builds Firestore's large C++ dependencies (abseil,\n     gRPC, BoringSSL) from source rather than, by default, using existing binaries.\n\nTo enable an env var within Xcode, quit the current Xcode instance, and open it from the command\nline, passing each desired env var with the `--env` argument.\n```console\nopen --env FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT --env FIREBASE_SOURCE_FIRESTORE \\\nPackage.swift\n```\n\nTo unset the env vars, quit the running Xcode instance.\n\n#### 2. CocoaPods\n\n1.  **Generate Workspace**: After generating a workspace using `pod gen ...` as described in the\n    \"Setup Commands\" section.\n2.  **Run Tests**:\n    *   Open the generated `.xcworkspace`.\n    *   Select the appropriate scheme for the unit tests of the library\n        (e.g., `FirebaseStorage-Unit-unit`).\n    *   Press `⌘U` or click the \"play\" arrow to run tests.\n\n### Code Coverage\n\n*   **Enable in Xcode**:\n    1.  Go to `Product → Scheme ➞ Edit Scheme...` (or use `⌥⌘U`).\n    2.  Select the \"Test\" action in the sidebar.\n    3.  Go to the \"Options\" tab.\n    4.  Check the \"Code Coverage\" box.\n*   **Coverage Report Tool**: The repository includes a tool for generating more detailed\n    coverage reports. Refer to its documentation: `scripts/code_coverage_report/README.md`.\n\n### Handling `GoogleService-Info.plist` in Tests\n\nConfiguration files like `GoogleService-Info.plist` are necessary for Firebase SDKs to connect to\na backend project. How these are handled in tests varies:\n\n*   **Unit Tests**:\n    *   Unit tests should generally not rely on a live backend or a real\n        `GoogleService-Info.plist`.\n    *   Where configuration is needed (e.g., for `FirebaseApp.configure()`), tests often use\n        mock or fake `GoogleService-Info.plist` files with dummy values. These are typically\n        included directly in the test target's resources. Be aware of this pattern if tests\n        seem to require Firebase app initialization.\n*   **Integration Tests & Sample Apps**:\n    *   Integration tests and sample apps, which do interact with live backends, require valid\n        `GoogleService-Info.plist` files.\n    *   In the CI (Continuous Integration) environment, these files are usually provided\n        securely (e.g., via environment variables, mounted secrets, or dedicated build steps\n        that place the correct plist). As an AI agent, you typically won't manage these CI\n        secrets directly.\n    *   If integration tests fail due to configuration issues, it might relate to how the CI\n        environment provides this plist.\n    *   For local execution of sample apps or some integration tests (if specifically requested\n        for a task), a valid plist obtained from the Firebase console for a test project would\n        be needed, as described in the original `README.md`. However, direct interaction with\n        the Firebase console to download plists is outside typical AI agent operations unless\n        explicitly guided.\n\n### Product-Specific Testing Notes\n\n*   **Firebase Database**:\n    *   Integration tests can run against a local Database Emulator or a production instance.\n    *   **Emulator**: Run `./scripts/run_database_emulator.sh start` before executing tests.\n    *   **Production**: Provide a valid `GoogleService-Info.plist` (copied to\n        `FirebaseDatabase/Tests/Resources/GoogleService-Info.plist`) and ensure security rules\n        are public during the test run.\n*   **Firebase Storage**:\n    *   For integration tests, follow instructions in\n        `FirebaseStorage/Tests/Integration/StorageIntegration.swift`.\n*   **Push Notifications (General for Messaging, etc.)**:\n    *   Cannot be tested on the iOS Simulator; requires a physical device.\n    *   Requires specific App ID provisioning in the Apple Developer portal.\n    *   Upload your APNs Provider Authentication Key or certificate to the Firebase Console.\n    *   Ensure the test device is registered in your Apple Developer account.\n\n## API Surface\n\nDesigning and maintaining a consistent and developer-friendly API is critical for the Firebase\nSDK. Adherence to established guidelines is important for a good user experience and should be\nfollowed when tasks involve API modifications.\n\n### Guiding Principles for New APIs\n\nThe primary reference for API design is `docs/firebase-api-guidelines.md`. Key principles for new\nAPI designs include:\n\n*   **Swift-First**: New APIs should be designed and implemented in Swift. Objective-C APIs\n    require strong justification. Generated Swift interfaces for Objective-C APIs should be\n    manually refined for Swift idioms if necessary.\n*   **Swift Code Samples**: Swift code samples should be prioritized in API proposals and\n    documentation.\n*   **Async/Await**: New asynchronous APIs should use Swift's `async/await`. Callback-based APIs\n    require justification (though callbacks are still appropriate for event handlers).\n    ```swift\n    // Preferred\n    public func fetchData() async throws -> Data { /* ... */ }\n\n    // Pre-Swift Concurrency (No longer preferred for new async APIs)\n    public func fetchData(completion: (Data?, Error?) -> Void) { /* ... */ }\n    ```\n*   **Sendable Types**: New APIs should be `Sendable` where applicable, to allow safe use in\n    concurrent contexts (e.g., within a `Task`).\n*   **Access Control**:\n    *   `public` access level should be used for new Swift APIs rather than `open`.\n    *   New Swift classes should generally be `final` to prevent subclassing, unless subclassing\n        is an intended design feature.\n*   **API Availability**:\n    *   The `@available` attribute is used to specify platform and version compatibility (e.g.,\n        `@available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)`).\n    *   The minimum supported versions for SPM are often tied to Analytics/Crashlytics. For other\n        APIs, the product's CocoaPods podspec is the reference for versioning in `@available`.\n*   **Constants**:\n    *   Constants in Swift should be defined within case-less enums (prevents instantiation).\n    *   The \"k\" prefix for Swift constants should be avoided.\n    ```swift\n    public enum NetworkConstants {\n        public static let httpPostMethod = \"POST\"\n    }\n    ```\n*   **Minimize Optionals**: While Swift's optionals provide type safety for nullability, their\n    overuse should be avoided to prevent complicating call sites.\n*   **Structs vs. Enums for Extensibility**:\n    *   For sets of values that might expand in the future, `structs` with static factory\n        methods are preferred over `enums`. Adding a case to a public Swift enum is a breaking\n        change.\n    *   See `docs/firebase-api-guidelines.md` (links to PRs #13728, #13976) for examples.\n*   **Avoid `Any`, `AnyObject`, NS-Types**: `Any`, `AnyObject`, or Objective-C NS-prefixed types\n    (like `NSString`, `NSDictionary`) should not be used in public Swift APIs. Swift native\n    types (`String`, `Dictionary`) are preferred, and heterogeneous collections should be\n    modeled with enums or structs for type safety.\n*   **Documentation**: New APIs must be documented using Swift-flavored Markdown. Xcode's `⌥ ⌘ /`\n    shortcut can generate documentation block structure.\n*   **Naming Conventions**:\n    *   Clarity and expressiveness should be prioritized (e.g., `fetchMetadata()` over `fetch()`\n        or `getMetadata()`).\n    *   Consistency with existing Firebase APIs must be maintained.\n    *   Refer to [Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).\n*   **Error Handling**:\n    *   APIs that can fail should be marked with `throws`.\n    *   Public error types conforming to Swift's `Error` protocol should be defined and thrown.\n*   **Objective-C (If Necessary)**:\n    *   Defining `typedefs` in public Objective-C headers should be avoided as they obscure the\n        underlying type in the generated Swift interface. Full types should be used.\n\n### Header Management and Imports\n\nThe document `HeadersImports.md` provides detailed guidelines. Key points include:\n\n*   **Public Headers**:\n    *   Define the library's public API.\n    *   Located in `FirebaseFoo/Sources/Public/FirebaseFoo/`.\n    *   Additions are minor version updates; changes/deletions are major.\n*   **Public Umbrella Header**:\n    *   A single header including the library's full public API\n        (e.g., `FirebaseFoo/Sources/Public/FirebaseFoo/FirebaseFoo.h`).\n*   **Private Headers**:\n    *   Located in `FirebaseFoo/Sources/Private/`.\n    *   Available to other libraries within the `firebase-ios-sdk` repo but NOT part of the\n        public API.\n    *   For CocoaPods, these are included in `source_files`, not `private_header_files`.\n*   **Interop Headers**:\n    *   Special private headers for defining interfaces between libraries\n        (see `Interop/FirebaseComponentSystem.md`).\n*   **Private Umbrella Header**:\n    *   Includes public API + private APIs for other in-repo libraries. Package manager\n        complexities should be localized here.\n*   **Library Internal Headers**:\n    *   Only used by the enclosing library, located among its source files.\n*   **Import Styles**:\n    *   **Within the same library**: Use repo-relative paths\n        (e.g., `#import \"FirebaseFoo/Sources/Internal/MyInternalHeader.h\"`).\n        *   *Exception*: Public headers importing other public headers from the *same library*\n            should use unqualified imports (`#import \"AnotherPublicHeaderInFoo.h\"`) to avoid\n            module collisions.\n    *   **Private Headers from other libraries**: Import the private umbrella header\n        (e.g., `#import \"FirebaseCore/Extension/FirebaseCoreInternal.h\"`).\n    *   **External Dependencies**:\n        ```objectivec\n        #if SWIFT_PACKAGE\n        @import GTMSessionFetcherCore;\n        #else\n        #import <GTMSessionFetcher/GTMSessionFetcher.h>\n        #endif\n        ```\n\nThis structure ensures that APIs are well-defined, discoverable, and maintainable across\ndifferent build systems and for various Firebase products.\n\n## Best Practices\n\nAdhering to best practices ensures code quality, maintainability, and a positive developer\nexperience for both contributors and users of the Firebase SDK.\n\n*   **Contribution Guidelines**: The `CONTRIBUTING.md` file contains detailed information on the\n    development workflow, pull requests, coding styles, and environment setup, which should be\n    adhered to.\n*   **Code of Conduct**: All contributions and interactions must align with the\n    [Code of Conduct](CODE_OF_CONDUCT.md).\n*   **Swift-First Development**: New features and APIs should prioritize Swift, as outlined in the\n    API guidelines. Objective-C is used only with strong justification.\n*   **Modularity**: The SDK's modular design, with each Firebase product in its own library/pod\n    (e.g., Auth, Firestore, Storage), promotes separation of concerns. Changes should generally\n    be focused within a product's dedicated directory.\n*   **Dependency Management**:\n    *   Internal dependencies (between Firebase pods) are managed via version specifications in\n        `.podspec` files or `Package.swift`.\n    *   External dependencies are also declared here. The impact of adding new external\n        dependencies requires careful consideration.\n*   **Central FirebaseApp (`FIRApp`)**:\n    *   `FirebaseApp` (Swift) / `FIRApp` (Objective-C) is the central class for initializing and\n        configuring Firebase.\n    *   It provides access to project-level configurations from `GoogleService-Info.plist`.\n*   **Component System (`FIRComponent`)**:\n    *   An internal component system (`FIRComponent`, `FIRComponentContainer`) is used for\n        registering and discovering Firebase services at runtime.\n    *   This enables a decoupled architecture. New top-level Firebase pods often require\n        registration with this system (see `docs/AddNewPod.md` and `FIRApp.m`).\n*   **`GoogleService-Info.plist` (in relation to SDK code)**:\n    *   While handling `GoogleService-Info.plist` in tests has specific considerations (see\n        \"Handling `GoogleService-Info.plist` in Tests\"), SDK code itself relies on `FirebaseApp`\n        to provide project configurations derived from such a file.\n*   **`-ObjC` Linker Flag**:\n    *   Awareness of the `-ObjC` \"Other Linker Flags\" setting is important, as it's necessary\n        for applications using Firebase Analytics (and often transitively, other Firebase SDKs)\n        to correctly link Objective-C categories.\n*   **Changelogs**: `CHANGELOG.md` files (root and product-specific) must be updated with\n    meaningful descriptions of changes for any pull request. The changelog\n    entry should always go into a new top-level `# Unreleased` section. If this\n    section does not already exist, you must create it at the top of the file.\n*   **Minimize Breaking Changes**: Breaking changes are avoided if possible and require careful\n    consideration, typically aligning with major version releases.\n*   **Platform Support**: Different levels of support exist for Apple platforms (macOS, Catalyst,\n    tvOS, visionOS, watchOS). `@available` and conditional compilation (`#if os(iOS)`) are\n    used. visionOS and watchOS are community-supported.\n*   **Header Hygiene**: Guidelines in `HeadersImports.md` must be followed strictly for\n    compatibility.\n*   **Testing**: Comprehensive testing (unit, integration) is a core best practice. Tests must\n    cover new code and bug fixes.\n\nAdherence to these practices helps maintain the quality and robustness of the Firebase Apple\nSDKs.\n\n## Common Patterns\n\nRecognizing the following common design and implementation patterns, prevalent throughout the\nFirebase Apple SDKs, facilitates understanding the existing codebase and developing new features\nconsistently.\n\n*   **Async/Await and Sendable for Swift**:\n    *   New asynchronous Swift code predominantly uses `async/await` for cleaner, more readable\n        control flow.\n    *   Types involved in concurrent operations are increasingly expected to conform to\n        `Sendable` to ensure thread safety, especially with Swift 6's stricter concurrency\n        checking.\n*   **Case-less Enums for Constants**:\n    *   Swift code uses case-less enums to group related constants, preventing instantiation and\n        providing a clear namespace.\n    ```swift\n    public enum StorageConstants {\n        public static let maxUploadRetryTime: TimeInterval = 600.0\n        public static let defaultChunkSize: Int64 = 256 * 1024\n    }\n    ```\n*   **Structs for Extensible Enum-like Values**:\n    *   When a set of predefined values (akin to enum cases) might need to be expanded without\n        causing breaking changes, `structs` with static factory methods are often used. This\n        avoids the issue where adding a new case to a public `enum` breaks client `switch`\n        statements. (See `docs/firebase-api-guidelines.md` for context).\n*   **Protocol Buffers (Protobuf / Nanopb)**:\n    *   Several modules (e.g., Crashlytics, Firestore, InAppMessaging, Performance, Messaging)\n        utilize Protocol Buffers for data serialization.\n    *   This involves `.proto` files defining data structures and scripts\n        (e.g., `generate_protos.sh`) for compilation into Swift or Objective-C (often Nanopb\n        for C/Objective-C). Due to their complexity and impact on build processes, introducing\n        Protobufs to new areas of the SDK should be avoided unless that area already heavily\n        relies on them or it's a specific requirement for interacting with an existing\n        Protobuf-based system.\n*   **API Visibility Layers (Public/Private/Internal)**:\n    *   A clear distinction is maintained for API visibility:\n        *   **Public**: APIs intended for end-users, found in `Sources/Public/` directories.\n            Changes here are subject to semantic versioning.\n        *   **Private**: APIs intended for use by *other Firebase SDKs within this repository*\n            but not for public consumption. Often found in `Sources/Private/` or `Interop/`\n            directories.\n        *   **Internal/Project**: Code and headers used only within the same library/module.\n            These are typically co-located with the module's other source files.\n*   **Umbrella Headers**:\n    *   **Public Umbrella Header**: Each library typically has a main public header\n        (e.g., `FirebaseFoo.h`) that includes all other public headers for that library,\n        simplifying imports for Objective-C users.\n    *   **Private Umbrella Header**: Some libraries may have an internal or extension umbrella\n        header (e.g., `FirebaseCoreInternal.h`) to expose necessary private APIs to other\n        Firebase libraries.\n*   **Module-Specific Prefixes (Objective-C)**:\n    *   Objective-C class names are typically prefixed to avoid collisions (e.g., `FIR` for\n        Firebase Core, `FST` for Firestore, `FIRCLS` for Crashlytics). This is less of a concern\n        in Swift due to namespacing with module names.\n*   **Error Handling Conventions**:\n    *   Swift: Adopts the `Error` protocol, with specific error enums/structs per module.\n    *   Objective-C: Uses `NSError**` parameters and standard error domains (often\n        module-specific).\n*   **Delegate Pattern (Objective-C & Swift)**:\n    *   Commonly used for callbacks and event notifications, especially in older Objective-C APIs\n        or when multiple distinct events need to be communicated.\n*   **Completion Handlers (Callbacks)**:\n    *   While `async/await` is preferred for new Swift asynchronous operations, completion\n        handlers remain prevalent in many existing Objective-C and Swift APIs. These typically\n        take `(ResultType?, Error?)` or similar parameters.\n*   **Singletons and Shared Instances**:\n    *   Many Firebase services offer a shared instance or singleton accessor\n        (e.g., `FirebaseApp.app()`, `Firestore.firestore()`, `Auth.auth()`).\n*   **Resource Bundles**:\n    *   SDKs requiring UI components or other resources (e.g., Firebase In-App Messaging) may\n        package them into `.bundle` files.\n*   **Use of `dispatch_once` / Lazy Initialization for Singletons (Objective-C)**:\n    *   This is a common Objective-C pattern for ensuring singleton instances are initialized\n        safely and only once. Swift employs `static let` properties for a similar outcome.\n\nUnderstanding these patterns is key to navigating the codebase and contributing effectively.\n\n## External Dependencies\n\nThe Firebase Apple SDK integrates several external open-source libraries to provide its\nfunctionality. These dependencies are managed as part of the overall SDK build and release\nprocess, primarily through CocoaPods and Swift Package Manager configurations.\n\nExamples of such dependencies include (but are not limited to):\n*   gRPC (for Firestore and other components)\n*   LevelDB (for Firestore local persistence)\n*   nanopb (for Protocol Buffer serialization in C/Objective-C contexts)\n*   abseil-cpp (common C++ libraries)\n*   GTMSessionFetcher (for networking)\n\nWhen working on tasks for this repository, **do not introduce new external dependencies** unless\nexplicitly instructed to do so by the user. Adding and managing dependencies in a large SDK like\nthis involves careful consideration of binary size, licensing, potential conflicts, and long-term\nmaintenance. The existing dependencies are curated and managed by the Firebase team. If a task\nseems to require functionality that might suggest a new library, discuss alternatives or confirm\nthe need for a new dependency with the user first.\n\n## Updating agents.md\n\nThis document (`agents.md`) is intended as a living guide to assist AI agents (like Jules) in\nunderstanding and contributing to the `firebase-ios-sdk` repository. As the SDK evolves, new\npatterns may emerge, best practices might be updated, or setup procedures could change.\n\n**Guideline for Future Tasks:**\nIf, during the course of completing new tasks, you identify:\n*   New common patterns or architectural decisions.\n*   Changes to the build, test, or setup process.\n*   Updates to API design philosophies or best practices.\n*   Any other information that would be beneficial for an AI agent to have context on this\n    repository.\n\nPlease consider updating this `agents.md` file to reflect those new findings. Keeping this\ndocument current will improve the efficiency and accuracy of future AI-assisted development.\n\n## Technical Debt & Known Issues\n\n*   **Remote Config Memory & Concurrency**:\n    *   `setCustomSignals:` also strongly captures `self` via `self->_settings.customSignals`.\n    *   There is a deadlock hazard in `configValueForKey:` due to synchronous dispatch to `_queue` which then dispatches asynchronously back to `_queue` via `callListeners:`.\n    *   `RCNConfigExperiment` has data race risks on `_experimentPayloads` and other mutable collections as they are mutated from different queues (e.g., `loadExperimentFromTable` vs `updateExperimentsWithResponse:`).\n    *   In `RCNConfigExperiment`, `updateActiveExperimentsInDB` performs asynchronous DB operations. Subsequent code in `updateExperimentsWithHandler:` (such as `updateExperimentsWithServiceOrigin:`) is not guaranteed to execute after the DB updates complete, leading to a potential race condition.\n\n## AI Subagent Personas\n\nThe following personas are defined for use by AI orchestrators (like the\n`autonomous-tdd-loop` skill).\n\n### Objective Code Verifier\n**Role:** Objective Code Verifier\n**Prompt Guidelines:** Your job is strictly to run builds and test suites. Use\nthe `./scripts/style.sh` for formatting checks, and\n`./scripts/setup_spm_tests.sh` followed by `xcodebuild` (or `pod gen` and\n`xcodebuild` for CocoaPods) as dictated by the orchestrator. You are to report\na binary pass/fail result along with the specific error output if a failure\noccurs. Do not attempt to fix the code yourself unless specifically instructed.\n\n### Rigorous Code Reviewer\n**Role:** Rigorous Code Reviewer\n**Prompt Guidelines:** Your job is to perform a subjective, rigorous code\nreview on proposed changes. Focus on concurrency (Swift 6 strict concurrency),\nmemory management (retain cycles, etc.), API design (following\n`docs/firebase-api-guidelines.md`), and overall architectural consistency with\nthe rest of the Firebase iOS SDK. You should enforce best practices and flag\nany issues for the main agent to address.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# agents.md - Context for AI Assisted Development\n\nThis file highlights key aspects of the development environment, coding practices, and\narchitectural patterns covered in this repo. When an agents.md file is present in a product's\nsubdirectory, prefer using the workflow defined there.\n\n## Setup Commands\n\nTo contribute to or develop within the `firebase-ios-sdk` repository, an understanding of the\nfollowing setup is beneficial.\n\n### Prerequisites\n\n1.  **Xcode**: The development environment relies on Xcode 26.2 or above.\n2.  **Command-Line Tools**:\n    *   `clang-format`: Used for C, C++, and Objective-C code formatting. Version 23 is\n        specifically mentioned.\n    *   `mint`: Used to install and run Swift command-line tools, including `swiftformat` for\n        Swift code styling.\n    *   Note: The build environment uses `clang-format` (version 23) and `mint` (for\n        `swiftformat`) for code styling. Ensure any generated or modified code adheres to these\n        styling requirements.\n\n### Development Workflows\n\nYou can develop Firebase libraries using either Swift Package Manager (SPM) or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\nSwift Package Manager (SPM) is a primary development workflow. The project is typically opened\nvia the `Package.swift` file at the repository root.\n\n*   When working with SPM, specific library schemes (e.g., `FirebaseAuth`, `FirebaseFirestore`)\n    are used to build and develop individual modules.\n*   For test-related tasks using SPM, be aware of the `./scripts/setup_spm_tests.sh` script, which\n    configures Xcode to show schemes for testing individual packages. This script may need to be\n    invoked if tests need to be run or modified in an SPM context.\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n\n#### 2. CocoaPods\n\nCocoaPods (v1.12.0+) is another key development workflow.\n\n*   The `cocoapods-generate` plugin is used to create a development workspace from a `.podspec`\n    file.\n*   Development workspaces for individual libraries (e.g., `FirebaseStorage`) are generated using\n    a command like:\n    ```bash\n    pod gen FirebaseStorage.podspec --local-sources=./ --auto-open --platforms=ios\n    ```\n    *   Replace `FirebaseStorage.podspec` with the podspec of the library you intend to develop.\n        Podspecs are located in the root directory.\n    *   The `--local-sources=./` flag tells CocoaPods to use the local checkout of the SDK.\n    *   `--platforms` can be set to `ios`, `macos`, or `tvos`. Note that for Xcode 10.2+,\n        multi-platform CocoaPods workspaces might have issues, so generating for a single\n        platform is advised by `README.md`.\n    *   If the CocoaPods cache is outdated, you might need to run `pod repo update` first.\n*   Understanding this command structure is important if tasks involve setting up or modifying a\n    CocoaPods-based development environment for a specific module.\n*   **Mac Catalyst Development**:\n    1.  Run `pod gen` as above for `ios`.\n    2.  In the generated project, check the \"Mac\" box in the host app's \"Build Settings\" under\n        Deployment.\n    3.  Configure signing for the host app in \"Signing & Capabilities.\"\n    4.  In the \"Pods\" project, add signing to the host app and unit test targets.\n    5.  Alternatively, disable code signing by adding a user-defined setting\n        `CODE_SIGNING_REQUIRED` with value `NO` to each relevant target's build settings.\n\n### Code Styling\n\nCode consistency is maintained by `clang-format` (for C-based languages) and `swiftformat` (for\nSwift). Any code generated or modified must adhere to these standards.\n\n*   The `./scripts/style.sh` script is used to apply formatting. If a task involves code\n    changes, this script (or the underlying tools) should be used to ensure compliance:\n    ```bash\n    ./scripts/style.sh {path_to_changed_files_or_branch_name}\n    ```\n    For example:\n    ```bash\n    ./scripts/style.sh FirebaseStorage/Sources/\n    # OR\n    ./scripts/style.sh my-feature-branch\n    ```\n    Running `./scripts/style.sh` with no arguments will format all eligible files in the\n    repository.\n*   Failures in CI style checks often indicate that code modifications were not formatted\n    correctly with these tools.\n\n### Firestore Specific Development\n\nFirestore has a self-contained Xcode project. For details, refer to `Firestore/README.md`.\n\n## Testing\n\nThorough testing is essential for maintaining the quality and stability of the Firebase SDK.\n\n### General Guidelines\n\n*   **Write Tests**:\n    *   When fixing a bug, add a test to prevent regressions.\n    *   When adding a new feature, include tests to validate the new or modified APIs.\n*   **Tests as Documentation**: Well-written tests can serve as examples of how to use an API.\n*   **Code Coverage**: Aim for good code coverage to ensure all critical paths are tested.\n\n### Running Tests\n\nThe primary method for running tests is through Xcode, after setting up your development\nenvironment using either Swift Package Manager or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\n1.  **Enable Test Schemes**: If you haven't already, run the script from the repository root:\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n2.  **Run Tests**:\n    *   In Xcode, select the scheme corresponding to the library or test suite you want to run\n        (e.g., `FirebaseFirestoreTests`).\n    *   Choose the target platform (run destination) along with the scheme.\n    *   Press `⌘U` or click the \"play\" arrow in the project navigation bar to run the tests.\n    *   Note: `CONTRIBUTING.md` mentions that not all test schemes might be configured to run\n        with SPM.\n\n##### Environment Variables in SwiftPM\n\nThe following are environment variables to modify sources of code that can help with testing\nspecific frameworks or dealing with version mismatches.\n*   `FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT`: When passed, sets the dependency on the\n    https://github.com/google/GoogleAppMeasurement.git package to use the main branch. This is\n    done to keep the Firebase package's main branch building when it depends on unreleased changes\n    in the GoogleAppMeasurement package's main branch. Use it when you run into version issues.\n*   `FIREBASECI_USE_LOCAL_FIRESTORE_ZIP`: When passed, looks for a local\n    `FirebaseFirestoreInternal.xcframework` framework at the root of the repo to resolve the\n    Firestore target. Used for testing incombination with `scripts/check_firestore_symbols.sh`.\n*   `FIREBASE_SOURCE_FIRESTORE`: When passed, builds Firestore's large C++ dependencies (abseil,\n     gRPC, BoringSSL) from source rather than, by default, using existing binaries.\n\nTo enable an env var within Xcode, quit the current Xcode instance, and open it from the command\nline, passing each desired env var with the `--env` argument.\n```console\nopen --env FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT --env FIREBASE_SOURCE_FIRESTORE \\\nPackage.swift\n```\n\nTo unset the env vars, quit the running Xcode instance.\n\n#### 2. CocoaPods\n\n1.  **Generate Workspace**: After generating a workspace using `pod gen ...` as described in the\n    \"Setup Commands\" section.\n2.  **Run Tests**:\n    *   Open the generated `.xcworkspace`.\n    *   Select the appropriate scheme for the unit tests of the library\n        (e.g., `FirebaseStorage-Unit-unit`).\n    *   Press `⌘U` or click the \"play\" arrow to run tests.\n\n### Code Coverage\n\n*   **Enable in Xcode**:\n    1.  Go to `Product → Scheme ➞ Edit Scheme...` (or use `⌥⌘U`).\n    2.  Select the \"Test\" action in the sidebar.\n    3.  Go to the \"Options\" tab.\n    4.  Check the \"Code Coverage\" box.\n*   **Coverage Report Tool**: The repository includes a tool for generating more detailed\n    coverage reports. Refer to its documentation: `scripts/code_coverage_report/README.md`.\n\n### Handling `GoogleService-Info.plist` in Tests\n\nConfiguration files like `GoogleService-Info.plist` are necessary for Firebase SDKs to connect to\na backend project. How these are handled in tests varies:\n\n*   **Unit Tests**:\n    *   Unit tests should generally not rely on a live backend or a real\n        `GoogleService-Info.plist`.\n    *   Where configuration is needed (e.g., for `FirebaseApp.configure()`), tests often use\n        mock or fake `GoogleService-Info.plist` files with dummy values. These are typically\n        included directly in the test target's resources. Be aware of this pattern if tests\n        seem to require Firebase app initialization.\n*   **Integration Tests & Sample Apps**:\n    *   Integration tests and sample apps, which do interact with live backends, require valid\n        `GoogleService-Info.plist` files.\n    *   In the CI (Continuous Integration) environment, these files are usually provided\n        securely (e.g., via environment variables, mounted secrets, or dedicated build steps\n        that place the correct plist). As an AI agent, you typically won't manage these CI\n        secrets directly.\n    *   If integration tests fail due to configuration issues, it might relate to how the CI\n        environment provides this plist.\n    *   For local execution of sample apps or some integration tests (if specifically requested\n        for a task), a valid plist obtained from the Firebase console for a test project would\n        be needed, as described in the original `README.md`. However, direct interaction with\n        the Firebase console to download plists is outside typical AI agent operations unless\n        explicitly guided.\n\n### Product-Specific Testing Notes\n\n*   **Firebase Database**:\n    *   Integration tests can run against a local Database Emulator or a production instance.\n    *   **Emulator**: Run `./scripts/run_database_emulator.sh start` before executing tests.\n    *   **Production**: Provide a valid `GoogleService-Info.plist` (copied to\n        `FirebaseDatabase/Tests/Resources/GoogleService-Info.plist`) and ensure security rules\n        are public during the test run.\n*   **Firebase Storage**:\n    *   For integration tests, follow instructions in\n        `FirebaseStorage/Tests/Integration/StorageIntegration.swift`.\n*   **Push Notifications (General for Messaging, etc.)**:\n    *   Cannot be tested on the iOS Simulator; requires a physical device.\n    *   Requires specific App ID provisioning in the Apple Developer portal.\n    *   Upload your APNs Provider Authentication Key or certificate to the Firebase Console.\n    *   Ensure the test device is registered in your Apple Developer account.\n\n## API Surface\n\nDesigning and maintaining a consistent and developer-friendly API is critical for the Firebase\nSDK. Adherence to established guidelines is important for a good user experience and should be\nfollowed when tasks involve API modifications.\n\n### Guiding Principles for New APIs\n\nThe primary reference for API design is `docs/firebase-api-guidelines.md`. Key principles for new\nAPI designs include:\n\n*   **Swift-First**: New APIs should be designed and implemented in Swift. Objective-C APIs\n    require strong justification. Generated Swift interfaces for Objective-C APIs should be\n    manually refined for Swift idioms if necessary.\n*   **Swift Code Samples**: Swift code samples should be prioritized in API proposals and\n    documentation.\n*   **Async/Await**: New asynchronous APIs should use Swift's `async/await`. Callback-based APIs\n    require justification (though callbacks are still appropriate for event handlers).\n    ```swift\n    // Preferred\n    public func fetchData() async throws -> Data { /* ... */ }\n\n    // Pre-Swift Concurrency (No longer preferred for new async APIs)\n    public func fetchData(completion: (Data?, Error?) -> Void) { /* ... */ }\n    ```\n*   **Sendable Types**: New APIs should be `Sendable` where applicable, to allow safe use in\n    concurrent contexts (e.g., within a `Task`).\n*   **Access Control**:\n    *   `public` access level should be used for new Swift APIs rather than `open`.\n    *   New Swift classes should generally be `final` to prevent subclassing, unless subclassing\n        is an intended design feature.\n*   **API Availability**:\n    *   The `@available` attribute is used to specify platform and version compatibility (e.g.,\n        `@available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)`).\n    *   The minimum supported versions for SPM are often tied to Analytics/Crashlytics. For other\n        APIs, the product's CocoaPods podspec is the reference for versioning in `@available`.\n*   **Constants**:\n    *   Constants in Swift should be defined within case-less enums (prevents instantiation).\n    *   The \"k\" prefix for Swift constants should be avoided.\n    ```swift\n    public enum NetworkConstants {\n        public static let httpPostMethod = \"POST\"\n    }\n    ```\n*   **Minimize Optionals**: While Swift's optionals provide type safety for nullability, their\n    overuse should be avoided to prevent complicating call sites.\n*   **Structs vs. Enums for Extensibility**:\n    *   For sets of values that might expand in the future, `structs` with static factory\n        methods are preferred over `enums`. Adding a case to a public Swift enum is a breaking\n        change.\n    *   See `docs/firebase-api-guidelines.md` (links to PRs #13728, #13976) for examples.\n*   **Avoid `Any`, `AnyObject`, NS-Types**: `Any`, `AnyObject`, or Objective-C NS-prefixed types\n    (like `NSString`, `NSDictionary`) should not be used in public Swift APIs. Swift native\n    types (`String`, `Dictionary`) are preferred, and heterogeneous collections should be\n    modeled with enums or structs for type safety.\n*   **Documentation**: New APIs must be documented using Swift-flavored Markdown. Xcode's `⌥ ⌘ /`\n    shortcut can generate documentation block structure.\n*   **Naming Conventions**:\n    *   Clarity and expressiveness should be prioritized (e.g., `fetchMetadata()` over `fetch()`\n        or `getMetadata()`).\n    *   Consistency with existing Firebase APIs must be maintained.\n    *   Refer to [Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).\n*   **Error Handling**:\n    *   APIs that can fail should be marked with `throws`.\n    *   Public error types conforming to Swift's `Error` protocol should be defined and thrown.\n*   **Objective-C (If Necessary)**:\n    *   Defining `typedefs` in public Objective-C headers should be avoided as they obscure the\n        underlying type in the generated Swift interface. Full types should be used.\n\n### Header Management and Imports\n\nThe document `HeadersImports.md` provides detailed guidelines. Key points include:\n\n*   **Public Headers**:\n    *   Define the library's public API.\n    *   Located in `FirebaseFoo/Sources/Public/FirebaseFoo/`.\n    *   Additions are minor version updates; changes/deletions are major.\n*   **Public Umbrella Header**:\n    *   A single header including the library's full public API\n        (e.g., `FirebaseFoo/Sources/Public/FirebaseFoo/FirebaseFoo.h`).\n*   **Private Headers**:\n    *   Located in `FirebaseFoo/Sources/Private/`.\n    *   Available to other libraries within the `firebase-ios-sdk` repo but NOT part of the\n        public API.\n    *   For CocoaPods, these are included in `source_files`, not `private_header_files`.\n*   **Interop Headers**:\n    *   Special private headers for defining interfaces between libraries\n        (see `Interop/FirebaseComponentSystem.md`).\n*   **Private Umbrella Header**:\n    *   Includes public API + private APIs for other in-repo libraries. Package manager\n        complexities should be localized here.\n*   **Library Internal Headers**:\n    *   Only used by the enclosing library, located among its source files.\n*   **Import Styles**:\n    *   **Within the same library**: Use repo-relative paths\n        (e.g., `#import \"FirebaseFoo/Sources/Internal/MyInternalHeader.h\"`).\n        *   *Exception*: Public headers importing other public headers from the *same library*\n            should use unqualified imports (`#import \"AnotherPublicHeaderInFoo.h\"`) to avoid\n            module collisions.\n    *   **Private Headers from other libraries**: Import the private umbrella header\n        (e.g., `#import \"FirebaseCore/Extension/FirebaseCoreInternal.h\"`).\n    *   **External Dependencies**:\n        ```objectivec\n        #if SWIFT_PACKAGE\n        @import GTMSessionFetcherCore;\n        #else\n        #import <GTMSessionFetcher/GTMSessionFetcher.h>\n        #endif\n        ```\n\nThis structure ensures that APIs are well-defined, discoverable, and maintainable across\ndifferent build systems and for various Firebase products.\n\n## Best Practices\n\nAdhering to best practices ensures code quality, maintainability, and a positive developer\nexperience for both contributors and users of the Firebase SDK.\n\n*   **Contribution Guidelines**: The `CONTRIBUTING.md` file contains detailed information on the\n    development workflow, pull requests, coding styles, and environment setup, which should be\n    adhered to.\n*   **Code of Conduct**: All contributions and interactions must align with the\n    [Code of Conduct](CODE_OF_CONDUCT.md).\n*   **Swift-First Development**: New features and APIs should prioritize Swift, as outlined in the\n    API guidelines. Objective-C is used only with strong justification.\n*   **Modularity**: The SDK's modular design, with each Firebase product in its own library/pod\n    (e.g., Auth, Firestore, Storage), promotes separation of concerns. Changes should generally\n    be focused within a product's dedicated directory.\n*   **Dependency Management**:\n    *   Internal dependencies (between Firebase pods) are managed via version specifications in\n        `.podspec` files or `Package.swift`.\n    *   External dependencies are also declared here. The impact of adding new external\n        dependencies requires careful consideration.\n*   **Central FirebaseApp (`FIRApp`)**:\n    *   `FirebaseApp` (Swift) / `FIRApp` (Objective-C) is the central class for initializing and\n        configuring Firebase.\n    *   It provides access to project-level configurations from `GoogleService-Info.plist`.\n*   **Component System (`FIRComponent`)**:\n    *   An internal component system (`FIRComponent`, `FIRComponentContainer`) is used for\n        registering and discovering Firebase services at runtime.\n    *   This enables a decoupled architecture. New top-level Firebase pods often require\n        registration with this system (see `docs/AddNewPod.md` and `FIRApp.m`).\n*   **`GoogleService-Info.plist` (in relation to SDK code)**:\n    *   While handling `GoogleService-Info.plist` in tests has specific considerations (see\n        \"Handling `GoogleService-Info.plist` in Tests\"), SDK code itself relies on `FirebaseApp`\n        to provide project configurations derived from such a file.\n*   **`-ObjC` Linker Flag**:\n    *   Awareness of the `-ObjC` \"Other Linker Flags\" setting is important, as it's necessary\n        for applications using Firebase Analytics (and often transitively, other Firebase SDKs)\n        to correctly link Objective-C categories.\n*   **Changelogs**: `CHANGELOG.md` files (root and product-specific) must be updated with\n    meaningful descriptions of changes for any pull request. The changelog\n    entry should always go into a new top-level `# Unreleased` section. If this\n    section does not already exist, you must create it at the top of the file.\n*   **Minimize Breaking Changes**: Breaking changes are avoided if possible and require careful\n    consideration, typically aligning with major version releases.\n*   **Platform Support**: Different levels of support exist for Apple platforms (macOS, Catalyst,\n    tvOS, visionOS, watchOS). `@available` and conditional compilation (`#if os(iOS)`) are\n    used. visionOS and watchOS are community-supported.\n*   **Header Hygiene**: Guidelines in `HeadersImports.md` must be followed strictly for\n    compatibility.\n*   **Testing**: Comprehensive testing (unit, integration) is a core best practice. Tests must\n    cover new code and bug fixes.\n\nAdherence to these practices helps maintain the quality and robustness of the Firebase Apple\nSDKs.\n\n## Common Patterns\n\nRecognizing the following common design and implementation patterns, prevalent throughout the\nFirebase Apple SDKs, facilitates understanding the existing codebase and developing new features\nconsistently.\n\n*   **Async/Await and Sendable for Swift**:\n    *   New asynchronous Swift code predominantly uses `async/await` for cleaner, more readable\n        control flow.\n    *   Types involved in concurrent operations are increasingly expected to conform to\n        `Sendable` to ensure thread safety, especially with Swift 6's stricter concurrency\n        checking.\n*   **Case-less Enums for Constants**:\n    *   Swift code uses case-less enums to group related constants, preventing instantiation and\n        providing a clear namespace.\n    ```swift\n    public enum StorageConstants {\n        public static let maxUploadRetryTime: TimeInterval = 600.0\n        public static let defaultChunkSize: Int64 = 256 * 1024\n    }\n    ```\n*   **Structs for Extensible Enum-like Values**:\n    *   When a set of predefined values (akin to enum cases) might need to be expanded without\n        causing breaking changes, `structs` with static factory methods are often used. This\n        avoids the issue where adding a new case to a public `enum` breaks client `switch`\n        statements. (See `docs/firebase-api-guidelines.md` for context).\n*   **Protocol Buffers (Protobuf / Nanopb)**:\n    *   Several modules (e.g., Crashlytics, Firestore, InAppMessaging, Performance, Messaging)\n        utilize Protocol Buffers for data serialization.\n    *   This involves `.proto` files defining data structures and scripts\n        (e.g., `generate_protos.sh`) for compilation into Swift or Objective-C (often Nanopb\n        for C/Objective-C). Due to their complexity and impact on build processes, introducing\n        Protobufs to new areas of the SDK should be avoided unless that area already heavily\n        relies on them or it's a specific requirement for interacting with an existing\n        Protobuf-based system.\n*   **API Visibility Layers (Public/Private/Internal)**:\n    *   A clear distinction is maintained for API visibility:\n        *   **Public**: APIs intended for end-users, found in `Sources/Public/` directories.\n            Changes here are subject to semantic versioning.\n        *   **Private**: APIs intended for use by *other Firebase SDKs within this repository*\n            but not for public consumption. Often found in `Sources/Private/` or `Interop/`\n            directories.\n        *   **Internal/Project**: Code and headers used only within the same library/module.\n            These are typically co-located with the module's other source files.\n*   **Umbrella Headers**:\n    *   **Public Umbrella Header**: Each library typically has a main public header\n        (e.g., `FirebaseFoo.h`) that includes all other public headers for that library,\n        simplifying imports for Objective-C users.\n    *   **Private Umbrella Header**: Some libraries may have an internal or extension umbrella\n        header (e.g., `FirebaseCoreInternal.h`) to expose necessary private APIs to other\n        Firebase libraries.\n*   **Module-Specific Prefixes (Objective-C)**:\n    *   Objective-C class names are typically prefixed to avoid collisions (e.g., `FIR` for\n        Firebase Core, `FST` for Firestore, `FIRCLS` for Crashlytics). This is less of a concern\n        in Swift due to namespacing with module names.\n*   **Error Handling Conventions**:\n    *   Swift: Adopts the `Error` protocol, with specific error enums/structs per module.\n    *   Objective-C: Uses `NSError**` parameters and standard error domains (often\n        module-specific).\n*   **Delegate Pattern (Objective-C & Swift)**:\n    *   Commonly used for callbacks and event notifications, especially in older Objective-C APIs\n        or when multiple distinct events need to be communicated.\n*   **Completion Handlers (Callbacks)**:\n    *   While `async/await` is preferred for new Swift asynchronous operations, completion\n        handlers remain prevalent in many existing Objective-C and Swift APIs. These typically\n        take `(ResultType?, Error?)` or similar parameters.\n*   **Singletons and Shared Instances**:\n    *   Many Firebase services offer a shared instance or singleton accessor\n        (e.g., `FirebaseApp.app()`, `Firestore.firestore()`, `Auth.auth()`).\n*   **Resource Bundles**:\n    *   SDKs requiring UI components or other resources (e.g., Firebase In-App Messaging) may\n        package them into `.bundle` files.\n*   **Use of `dispatch_once` / Lazy Initialization for Singletons (Objective-C)**:\n    *   This is a common Objective-C pattern for ensuring singleton instances are initialized\n        safely and only once. Swift employs `static let` properties for a similar outcome.\n\nUnderstanding these patterns is key to navigating the codebase and contributing effectively.\n\n## External Dependencies\n\nThe Firebase Apple SDK integrates several external open-source libraries to provide its\nfunctionality. These dependencies are managed as part of the overall SDK build and release\nprocess, primarily through CocoaPods and Swift Package Manager configurations.\n\nExamples of such dependencies include (but are not limited to):\n*   gRPC (for Firestore and other components)\n*   LevelDB (for Firestore local persistence)\n*   nanopb (for Protocol Buffer serialization in C/Objective-C contexts)\n*   abseil-cpp (common C++ libraries)\n*   GTMSessionFetcher (for networking)\n\nWhen working on tasks for this repository, **do not introduce new external dependencies** unless\nexplicitly instructed to do so by the user. Adding and managing dependencies in a large SDK like\nthis involves careful consideration of binary size, licensing, potential conflicts, and long-term\nmaintenance. The existing dependencies are curated and managed by the Firebase team. If a task\nseems to require functionality that might suggest a new library, discuss alternatives or confirm\nthe need for a new dependency with the user first.\n\n## Updating agents.md\n\nThis document (`agents.md`) is intended as a living guide to assist AI agents (like Jules) in\nunderstanding and contributing to the `firebase-ios-sdk` repository. As the SDK evolves, new\npatterns may emerge, best practices might be updated, or setup procedures could change.\n\n**Guideline for Future Tasks:**\nIf, during the course of completing new tasks, you identify:\n*   New common patterns or architectural decisions.\n*   Changes to the build, test, or setup process.\n*   Updates to API design philosophies or best practices.\n*   Any other information that would be beneficial for an AI agent to have context on this\n    repository.\n\nPlease consider updating this `agents.md` file to reflect those new findings. Keeping this\ndocument current will improve the efficiency and accuracy of future AI-assisted development.\n\n## Technical Debt & Known Issues\n\n*   **Remote Config Memory & Concurrency**:\n    *   `setCustomSignals:` also strongly captures `self` via `self->_settings.customSignals`.\n    *   There is a deadlock hazard in `configValueForKey:` due to synchronous dispatch to `_queue` which then dispatches asynchronously back to `_queue` via `callListeners:`.\n    *   `RCNConfigExperiment` has data race risks on `_experimentPayloads` and other mutable collections as they are mutated from different queues (e.g., `loadExperimentFromTable` vs `updateExperimentsWithResponse:`).\n    *   In `RCNConfigExperiment`, `updateActiveExperimentsInDB` performs asynchronous DB operations. Subsequent code in `updateExperimentsWithHandler:` (such as `updateExperimentsWithServiceOrigin:`) is not guaranteed to execute after the DB updates complete, leading to a potential race condition.\n\n## AI Subagent Personas\n\nThe following personas are defined for use by AI orchestrators (like the\n`autonomous-tdd-loop` skill).\n\n### Objective Code Verifier\n**Role:** Objective Code Verifier\n**Prompt Guidelines:** Your job is strictly to run builds and test suites. Use\nthe `./scripts/style.sh` for formatting checks, and\n`./scripts/setup_spm_tests.sh` followed by `xcodebuild` (or `pod gen` and\n`xcodebuild` for CocoaPods) as dictated by the orchestrator. You are to report\na binary pass/fail result along with the specific error output if a failure\noccurs. Do not attempt to fix the code yourself unless specifically instructed.\n\n### Rigorous Code Reviewer\n**Role:** Rigorous Code Reviewer\n**Prompt Guidelines:** Your job is to perform a subjective, rigorous code\nreview on proposed changes. Focus on concurrency (Swift 6 strict concurrency),\nmemory management (retain cycles, etc.), API design (following\n`docs/firebase-api-guidelines.md`), and overall architectural consistency with\nthe rest of the Firebase iOS SDK. You should enforce best practices and flag\nany issues for the main agent to address.\n","isInternal":false,"tokens":6432,"sizeBytes":28906},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":204},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":190},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":183}],"systemPromptSnippet":"<yakaai_skills repo=\"firebase/firebase-ios-sdk\">\n<!-- File: AGENTS.md (Tokens: ~6432 | Category: root-instruction) -->\n# agents.md - Context for AI Assisted Development\n\nThis file highlights key aspects of the development environment, coding practices, and\narchitectural patterns covered in this repo. When an agents.md file is present in a product's\nsubdirectory, prefer using the workflow defined there.\n\n## Setup Commands\n\nTo contribute to or develop within the `firebase-ios-sdk` repository, an understanding of the\nfollowing setup is beneficial.\n\n### Prerequisites\n\n1.  **Xcode**: The development environment relies on Xcode 26.2 or above.\n2.  **Command-Line Tools**:\n    *   `clang-format`: Used for C, C++, and Objective-C code formatting. Version 23 is\n        specifically mentioned.\n    *   `mint`: Used to install and run Swift command-line tools, including `swiftformat` for\n        Swift code styling.\n    *   Note: The build environment uses `clang-format` (version 23) and `mint` (for\n        `swiftformat`) for code styling. Ensure any generated or modified code adheres to these\n        styling requirements.\n\n### Development Workflows\n\nYou can develop Firebase libraries using either Swift Package Manager (SPM) or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\nSwift Package Manager (SPM) is a primary development workflow. The project is typically opened\nvia the `Package.swift` file at the repository root.\n\n*   When working with SPM, specific library schemes (e.g., `FirebaseAuth`, `FirebaseFirestore`)\n    are used to build and develop individual modules.\n*   For test-related tasks using SPM, be aware of the `./scripts/setup_spm_tests.sh` script, which\n    configures Xcode to show schemes for testing individual packages. This script may need to be\n    invoked if tests need to be run or modified in an SPM context.\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n\n#### 2. CocoaPods\n\nCocoaPods (v1.12.0+) is another key development workflow.\n\n*   The `cocoapods-generate` plugin is used to create a development workspace from a `.podspec`\n    file.\n*   Development workspaces for individual libraries (e.g., `FirebaseStorage`) are generated using\n    a command like:\n    ```bash\n    pod gen FirebaseStorage.podspec --local-sources=./ --auto-open --platforms=ios\n    ```\n    *   Replace `FirebaseStorage.podspec` with the podspec of the library you intend to develop.\n        Podspecs are located in the root directory.\n    *   The `--local-sources=./` flag tells CocoaPods to use the local checkout of the SDK.\n    *   `--platforms` can be set to `ios`, `macos`, or `tvos`. Note that for Xcode 10.2+,\n        multi-platform CocoaPods workspaces might have issues, so generating for a single\n        platform is advised by `README.md`.\n    *   If the CocoaPods cache is outdated, you might need to run `pod repo update` first.\n*   Understanding this command structure is important if tasks involve setting up or modifying a\n    CocoaPods-based development environment for a specific module.\n*   **Mac Catalyst Development**:\n    1.  Run `pod gen` as above for `ios`.\n    2.  In the generated project, check the \"Mac\" box in the host app's \"Build Settings\" under\n        Deployment.\n    3.  Configure signing for the host app in \"Signing & Capabilities.\"\n    4.  In the \"Pods\" project, add signing to the host app and unit test targets.\n    5.  Alternatively, disable code signing by adding a user-defined setting\n        `CODE_SIGNING_REQUIRED` with value `NO` to each relevant target's build settings.\n\n### Code Styling\n\nCode consistency is maintained by `clang-format` (for C-based languages) and `swiftformat` (for\nSwift). Any code generated or modified must adhere to these standards.\n\n*   The `./scripts/style.sh` script is used to apply formatting. If a task involves code\n    changes, this script (or the underlying tools) should be used to ensure compliance:\n    ```bash\n    ./scripts/style.sh {path_to_changed_files_or_branch_name}\n    ```\n    For example:\n    ```bash\n    ./scripts/style.sh FirebaseStorage/Sources/\n    # OR\n    ./scripts/style.sh my-feature-branch\n    ```\n    Running `./scripts/style.sh` with no arguments will format all eligible files in the\n    repository.\n*   Failures in CI style checks often indicate that code modifications were not formatted\n    correctly with these tools.\n\n### Firestore Specific Development\n\nFirestore has a self-contained Xcode project. For details, refer to `Firestore/README.md`.\n\n## Testing\n\nThorough testing is essential for maintaining the quality and stability of the Firebase SDK.\n\n### General Guidelines\n\n*   **Write Tests**:\n    *   When fixing a bug, add a test to prevent regressions.\n    *   When adding a new feature, include tests to validate the new or modified APIs.\n*   **Tests as Documentation**: Well-written tests can serve as examples of how to use an API.\n*   **Code Coverage**: Aim for good code coverage to ensure all critical paths are tested.\n\n### Running Tests\n\nThe primary method for running tests is through Xcode, after setting up your development\nenvironment using either Swift Package Manager or CocoaPods.\n\n#### 1. Swift Package Manager (SPM)\n\n1.  **Enable Test Schemes**: If you haven't already, run the script from the repository root:\n    ```bash\n    ./scripts/setup_spm_tests.sh\n    ```\n2.  **Run Tests**:\n    *   In Xcode, select the scheme corresponding to the library or test suite you want to run\n        (e.g., `FirebaseFirestoreTests`).\n    *   Choose the target platform (run destination) along with the scheme.\n    *   Press `⌘U` or click the \"play\" arrow in the project navigation bar to run the tests.\n    *   Note: `CONTRIBUTING.md` mentions that not all test schemes might be configured to run\n        with SPM.\n\n##### Environment Variables in SwiftPM\n\nThe following are environment variables to modify sources of code that can help with testing\nspecific frameworks or dealing with version mismatches.\n*   `FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT`: When passed, sets the dependency on the\n    https://github.com/google/GoogleAppMeasurement.git package to use the main branch. This is\n    done to keep the Firebase package's main branch building when it depends on unreleased changes\n    in the GoogleAppMeasurement package's main branch. Use it when you run into version issues.\n*   `FIREBASECI_USE_LOCAL_FIRESTORE_ZIP`: When passed, looks for a local\n    `FirebaseFirestoreInternal.xcframework` framework at the root of the repo to resolve the\n    Firestore target. Used for testing incombination with `scripts/check_firestore_symbols.sh`.\n*   `FIREBASE_SOURCE_FIRESTORE`: When passed, builds Firestore's large C++ dependencies (abseil,\n     gRPC, BoringSSL) from source rather than, by default, using existing binaries.\n\nTo enable an env var within Xcode, quit the current Xcode instance, and open it from the command\nline, passing each desired env var with the `--env` argument.\n```console\nopen --env FIREBASECI_USE_LATEST_GOOGLEAPPMEASUREMENT --env FIREBASE_SOURCE_FIRESTORE \\\nPackage.swift\n```\n\nTo unset the env vars, quit the running Xcode instance.\n\n#### 2. CocoaPods\n\n1.  **Generate Workspace**: After generating a workspace using `pod gen ...` as described in the\n    \"Setup Commands\" section.\n2.  **Run Tests**:\n    *   Open the generated `.xcworkspace`.\n    *   Select the appropriate scheme for the unit tests of the library\n        (e.g., `FirebaseStorage-Unit-unit`).\n    *   Press `⌘U` or click the \"play\" arrow to run tests.\n\n### Code Coverage\n\n*   **Enable in Xcode**:\n    1.  Go to `Product → Scheme ➞ Edit Scheme...` (or use `⌥⌘U`).\n    2.  Select the \"Test\" action in the sidebar.\n    3.  Go to the \"Options\" tab.\n    4.  Check the \"Code Coverage\" box.\n*   **Coverage Report Tool**: The repository includes a tool for generating more detailed\n    coverage reports. Refer to its documentation: `scripts/code_coverage_report/README.md`.\n\n### Handling `GoogleService-Info.plist` in Tests\n\nConfiguration files like `GoogleService-Info.plist` are necessary for Firebase SDKs to connect to\na backend project. How these are handled in tests varies:\n\n*   **Unit Tests**:\n    *   Unit tests should generally not rely on a live backend or a real\n        `GoogleService-Info.plist`.\n    *   Where configuration is needed (e.g., for `FirebaseApp.configure()`), tests often use\n        mock or fake `GoogleService-Info.plist` files with dummy values. These are typically\n        included directly in the test target's resources. Be aware of this pattern if tests\n        seem to require Firebase app initialization.\n*   **Integration Tests & Sample Apps**:\n    *   Integration tests and sample apps, which do interact with live backends, require valid\n        `GoogleService-Info.plist` files.\n    *   In the CI (Continuous Integration) environment, these files are usually provided\n        securely (e.g., via environment variables, mounted secrets, or dedicated build steps\n        that place the correct plist). As an AI agent, you typically won't manage these CI\n        secrets directly.\n    *   If integration tests fail due to configuration issues, it might relate to how the CI\n        environment provides this plist.\n    *   For local execution of sample apps or some integration tests (if specifically requested\n        for a task), a valid plist obtained from the Firebase console for a test project would\n        be needed, as described in the original `README.md`. However, direct interaction with\n        the Firebase console to download plists is outside typical AI agent operations unless\n        explicitly guided.\n\n### Product-Specific Testing Notes\n\n*   **Firebase Database**:\n    *   Integration tests can run against a local Database Emulator or a production instance.\n    *   **Emulator**: Run `./scripts/run_database_emulator.sh start` before executing tests.\n    *   **Production**: Provide a valid `GoogleService-Info.plist` (copied to\n        `FirebaseDatabase/Tests/Resources/GoogleService-Info.plist`) and ensure security rules\n        are public during the test run.\n*   **Firebase Storage**:\n    *   For integration tests, follow instructions in\n        `FirebaseStorage/Tests/Integration/StorageIntegration.swift`.\n*   **Push Notifications (General for Messaging, etc.)**:\n    *   Cannot be tested on the iOS Simulator; requires a physical device.\n    *   Requires specific App ID provisioning in the Apple Developer portal.\n    *   Upload your APNs Provider Authentication Key or certificate to the Firebase Console.\n    *   Ensure the test device is registered in your Apple Developer account.\n\n## API Surface\n\nDesigning and maintaining a consistent and developer-friendly API is critical for the Firebase\nSDK. Adherence to established guidelines is important for a good user experience and should be\nfollowed when tasks involve API modifications.\n\n### Guiding Principles for New APIs\n\nThe primary reference for API design is `docs/firebase-api-guidelines.md`. Key principles for new\nAPI designs include:\n\n*   **Swift-First**: New APIs should be designed and implemented in Swift. Objective-C APIs\n    require strong justification. Generated Swift interfaces for Objective-C APIs should be\n    manually refined for Swift idioms if necessary.\n*   **Swift Code Samples**: Swift code samples should be prioritized in API proposals and\n    documentation.\n*   **Async/Await**: New asynchronous APIs should use Swift's `async/await`. Callback-based APIs\n    require justification (though callbacks are still appropriate for event handlers).\n    ```swift\n    // Preferred\n    public func fetchData() async throws -> Data { /* ... */ }\n\n    // Pre-Swift Concurrency (No longer preferred for new async APIs)\n    public func fetchData(completion: (Data?, Error?) -> Void) { /* ... */ }\n    ```\n*   **Sendable Types**: New APIs should be `Sendable` where applicable, to allow safe use in\n    concurrent contexts (e.g., within a `Task`).\n*   **Access Control**:\n    *   `public` access level should be used for new Swift APIs rather than `open`.\n    *   New Swift classes should generally be `final` to prevent subclassing, unless subclassing\n        is an intended design feature.\n*   **API Availability**:\n    *   The `@available` attribute is used to specify platform and version compatibility (e.g.,\n        `@available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)`).\n    *   The minimum supported versions for SPM are often tied to Analytics/Crashlytics. For other\n        APIs, the product's CocoaPods podspec is the reference for versioning in `@available`.\n*   **Constants**:\n    *   Constants in Swift should be defined within case-less enums (prevents instantiation).\n    *   The \"k\" prefix for Swift constants should be avoided.\n    ```swift\n    public enum NetworkConstants {\n        public static let httpPostMethod = \"POST\"\n    }\n    ```\n*   **Minimize Optionals**: While Swift's optionals provide type safety for nullability, their\n    overuse should be avoided to prevent complicating call sites.\n*   **Structs vs. Enums for Extensibility**:\n    *   For sets of values that might expand in the future, `structs` with static factory\n        methods are preferred over `enums`. Adding a case to a public Swift enum is a breaking\n        change.\n    *   See `docs/firebase-api-guidelines.md` (links to PRs #13728, #13976) for examples.\n*   **Avoid `Any`, `AnyObject`, NS-Types**: `Any`, `AnyObject`, or Objective-C NS-prefixed types\n    (like `NSString`, `NSDictionary`) should not be used in public Swift APIs. Swift native\n    types (`String`, `Dictionary`) are preferred, and heterogeneous collections should be\n    modeled with enums or structs for type safety.\n*   **Documentation**: New APIs must be documented using Swift-flavored Markdown. Xcode's `⌥ ⌘ /`\n    shortcut can generate documentation block structure.\n*   **Naming Conventions**:\n    *   Clarity and expressiveness should be prioritized (e.g., `fetchMetadata()` over `fetch()`\n        or `getMetadata()`).\n    *   Consistency with existing Firebase APIs must be maintained.\n    *   Refer to [Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).\n*   **Error Handling**:\n    *   APIs that can fail should be marked with `throws`.\n    *   Public error types conforming to Swift's `Error` protocol should be defined and thrown.\n*   **Objective-C (If Necessary)**:\n    *   Defining `typedefs` in public Objective-C headers should be avoided as they obscure the\n        underlying type in the generated Swift interface. Full types should be used.\n\n### Header Management and Imports\n\nThe document `HeadersImports.md` provides detailed guidelines. Key points include:\n\n*   **Public Headers**:\n    *   Define the library's public API.\n    *   Located in `FirebaseFoo/Sources/Public/FirebaseFoo/`.\n    *   Additions are minor version updates; changes/deletions are major.\n*   **Public Umbrella Header**:\n    *   A single header including the library's full public API\n        (e.g., `FirebaseFoo/Sources/Public/FirebaseFoo/FirebaseFoo.h`).\n*   **Private Headers**:\n    *   Located in `FirebaseFoo/Sources/Private/`.\n    *   Available to other libraries within the `firebase-ios-sdk` repo but NOT part of the\n        public API.\n    *   For CocoaPods, these are included in `source_files`, not `private_header_files`.\n*   **Interop Headers**:\n    *   Special private headers for defining interfaces between libraries\n        (see `Interop/FirebaseComponentSystem.md`).\n*   **Private Umbrella Header**:\n    *   Includes public API + private APIs for other in-repo libraries. Package manager\n        complexities should be localized here.\n*   **Library Internal Headers**:\n    *   Only used by the enclosing library, located among its source files.\n*   **Import Styles**:\n    *   **Within the same library**: Use repo-relative paths\n        (e.g., `#import \"FirebaseFoo/Sources/Internal/MyInternalHeader.h\"`).\n        *   *Exception*: Public headers importing other public headers from the *same library*\n            should use unqualified imports (`#import \"AnotherPublicHeaderInFoo.h\"`) to avoid\n            module collisions.\n    *   **Private Headers from other libraries**: Import the private umbrella header\n        (e.g., `#import \"FirebaseCore/Extension/FirebaseCoreInternal.h\"`).\n    *   **External Dependencies**:\n        ```objectivec\n        #if SWIFT_PACKAGE\n        @import GTMSessionFetcherCore;\n        #else\n        #import <GTMSessionFetcher/GTMSessionFetcher.h>\n        #endif\n        ```\n\nThis structure ensures that APIs are well-defined, discoverable, and maintainable across\ndifferent build systems and for various Firebase products.\n\n## Best Practices\n\nAdhering to best practices ensures code quality, maintainability, and a positive developer\nexperience for both contributors and users of the Firebase SDK.\n\n*   **Contribution Guidelines**: The `CONTRIBUTING.md` file contains detailed information on the\n    development workflow, pull requests, coding styles, and environment setup, which should be\n    adhered to.\n*   **Code of Conduct**: All contributions and interactions must align with the\n    [Code of Conduct](CODE_OF_CONDUCT.md).\n*   **Swift-First Development**: New features and APIs should prioritize Swift, as outlined in the\n    API guidelines. Objective-C is used only with strong justification.\n*   **Modularity**: The SDK's modular design, with each Firebase product in its own library/pod\n    (e.g., Auth, Firestore, Storage), promotes separation of concerns. Changes should generally\n    be focused within a product's dedicated directory.\n*   **Dependency Management**:\n    *   Internal dependencies (between Firebase pods) are managed via version specifications in\n        `.podspec` files or `Package.swift`.\n    *   External dependencies are also declared here. The impact of adding new external\n        dependencies requires careful consideration.\n*   **Central FirebaseApp (`FIRApp`)**:\n    *   `FirebaseApp` (Swift) / `FIRApp` (Objective-C) is the central class for initializing and\n        configuring Firebase.\n    *   It provides access to project-level configurations from `GoogleService-Info.plist`.\n*   **Component System (`FIRComponent`)**:\n    *   An internal component system (`FIRComponent`, `FIRComponentContainer`) is used for\n        registering and discovering Firebase services at runtime.\n    *   This enables a decoupled architecture. New top-level Firebase pods often require\n        registration with this system (see `docs/AddNewPod.md` and `FIRApp.m`).\n*   **`GoogleService-Info.plist` (in relation to SDK code)**:\n    *   While handling `GoogleService-Info.plist` in tests has specific considerations (see\n        \"Handling `GoogleService-Info.plist` in Tests\"), SDK code itself relies on `FirebaseApp`\n        to provide project configurations derived from such a file.\n*   **`-ObjC` Linker Flag**:\n    *   Awareness of the `-ObjC` \"Other Linker Flags\" setting is important, as it's necessary\n        for applications using Firebase Analytics (and often transitively, other Firebase SDKs)\n        to correctly link Objective-C categories.\n*   **Changelogs**: `CHANGELOG.md` files (root and product-specific) must be updated with\n    meaningful descriptions of changes for any pull request. The changelog\n    entry should always go into a new top-level `# Unreleased` section. If this\n    section does not already exist, you must create it at the top of the file.\n*   **Minimize Breaking Changes**: Breaking changes are avoided if possible and require careful\n    consideration, typically aligning with major version releases.\n*   **Platform Support**: Different levels of support exist for Apple platforms (macOS, Catalyst,\n    tvOS, visionOS, watchOS). `@available` and conditional compilation (`#if os(iOS)`) are\n    used. visionOS and watchOS are community-supported.\n*   **Header Hygiene**: Guidelines in `HeadersImports.md` must be followed strictly for\n    compatibility.\n*   **Testing**: Comprehensive testing (unit, integration) is a core best practice. Tests must\n    cover new code and bug fixes.\n\nAdherence to these practices helps maintain the quality and robustness of the Firebase Apple\nSDKs.\n\n## Common Patterns\n\nRecognizing the following common design and implementation patterns, prevalent throughout the\nFirebase Apple SDKs, facilitates understanding the existing codebase and developing new features\nconsistently.\n\n*   **Async/Await and Sendable for Swift**:\n    *   New asynchronous Swift code predominantly uses `async/await` for cleaner, more readable\n        control flow.\n    *   Types involved in concurrent operations are increasingly expected to conform to\n        `Sendable` to ensure thread safety, especially with Swift 6's stricter concurrency\n        checking.\n*   **Case-less Enums for Constants**:\n    *   Swift code uses case-less enums to group related constants, preventing instantiation and\n        providing a clear namespace.\n    ```swift\n    public enum StorageConstants {\n        public static let maxUploadRetryTime: TimeInterval = 600.0\n        public static let defaultChunkSize: Int64 = 256 * 1024\n    }\n    ```\n*   **Structs for Extensible Enum-like Values**:\n    *   When a set of predefined values (akin to enum cases) might need to be expanded without\n        causing breaking changes, `structs` with static factory methods are often used. This\n        avoids the issue where adding a new case to a public `enum` breaks client `switch`\n        statements. (See `docs/firebase-api-guidelines.md` for context).\n*   **Protocol Buffers (Protobuf / Nanopb)**:\n    *   Several modules (e.g., Crashlytics, Firestore, InAppMessaging, Performance, Messaging)\n        utilize Protocol Buffers for data serialization.\n    *   This involves `.proto` files defining data structures and scripts\n        (e.g., `generate_protos.sh`) for compilation into Swift or Objective-C (often Nanopb\n        for C/Objective-C). Due to their complexity and impact on build processes, introducing\n        Protobufs to new areas of the SDK should be avoided unless that area already heavily\n        relies on them or it's a specific requirement for interacting with an existing\n        Protobuf-based system.\n*   **API Visibility Layers (Public/Private/Internal)**:\n    *   A clear distinction is maintained for API visibility:\n        *   **Public**: APIs intended for end-users, found in `Sources/Public/` directories.\n            Changes here are subject to semantic versioning.\n        *   **Private**: APIs intended for use by *other Firebase SDKs within this repository*\n            but not for public consumption. Often found in `Sources/Private/` or `Interop/`\n            directories.\n        *   **Internal/Project**: Code and headers used only within the same library/module.\n            These are typically co-located with the module's other source files.\n*   **Umbrella Headers**:\n    *   **Public Umbrella Header**: Each library typically has a main public header\n        (e.g., `FirebaseFoo.h`) that includes all other public headers for that library,\n        simplifying imports for Objective-C users.\n    *   **Private Umbrella Header**: Some libraries may have an internal or extension umbrella\n        header (e.g., `FirebaseCoreInternal.h`) to expose necessary private APIs to other\n        Firebase libraries.\n*   **Module-Specific Prefixes (Objective-C)**:\n    *   Objective-C class names are typically prefixed to avoid collisions (e.g., `FIR` for\n        Firebase Core, `FST` for Firestore, `FIRCLS` for Crashlytics). This is less of a concern\n        in Swift due to namespacing with module names.\n*   **Error Handling Conventions**:\n    *   Swift: Adopts the `Error` protocol, with specific error enums/structs per module.\n    *   Objective-C: Uses `NSError**` parameters and standard error domains (often\n        module-specific).\n*   **Delegate Pattern (Objective-C & Swift)**:\n    *   Commonly used for callbacks and event notifications, especially in older Objective-C APIs\n        or when multiple distinct events need to be communicated.\n*   **Completion Handlers (Callbacks)**:\n    *   While `async/await` is preferred for new Swift asynchronous operations, completion\n        handlers remain prevalent in many existing Objective-C and Swift APIs. These typically\n        take `(ResultType?, Error?)` or similar parameters.\n*   **Singletons and Shared Instances**:\n    *   Many Firebase services offer a shared instance or singleton accessor\n        (e.g., `FirebaseApp.app()`, `Firestore.firestore()`, `Auth.auth()`).\n*   **Resource Bundles**:\n    *   SDKs requiring UI components or other resources (e.g., Firebase In-App Messaging) may\n        package them into `.bundle` files.\n*   **Use of `dispatch_once` / Lazy Initialization for Singletons (Objective-C)**:\n    *   This is a common Objective-C pattern for ensuring singleton instances are initialized\n        safely and only once. Swift employs `static let` properties for a similar outcome.\n\nUnderstanding these patterns is key to navigating the codebase and contributing effectively.\n\n## External Dependencies\n\nThe Firebase Apple SDK integrates several external open-source libraries to provide its\nfunctionality. These dependencies are managed as part of the overall SDK build and release\nprocess, primarily through CocoaPods and Swift Package Manager configurations.\n\nExamples of such dependencies include (but are not limited to):\n*   gRPC (for Firestore and other components)\n*   LevelDB (for Firestore local persistence)\n*   nanopb (for Protocol Buffer serialization in C/Objective-C contexts)\n*   abseil-cpp (common C++ libraries)\n*   GTMSessionFetcher (for networking)\n\nWhen working on tasks for this repository, **do not introduce new external dependencies** unless\nexplicitly instructed to do so by the user. Adding and managing dependencies in a large SDK like\nthis involves careful consideration of binary size, licensing, potential conflicts, and long-term\nmaintenance. The existing dependencies are curated and managed by the Firebase team. If a task\nseems to require functionality that might suggest a new library, discuss alternatives or confirm\nthe need for a new dependency with the user first.\n\n## Updating agents.md\n\nThis document (`agents.md`) is intended as a living guide to assist AI agents (like Jules) in\nunderstanding and contributing to the `firebase-ios-sdk` repository. As the SDK evolves, new\npatterns may emerge, best practices might be updated, or setup procedures could change.\n\n**Guideline for Future Tasks:**\nIf, during the course of completing new tasks, you identify:\n*   New common patterns or architectural decisions.\n*   Changes to the build, test, or setup process.\n*   Updates to API design philosophies or best practices.\n*   Any other information that would be beneficial for an AI agent to have context on this\n    repository.\n\nPlease consider updating this `agents.md` file to reflect those new findings. Keeping this\ndocument current will improve the efficiency and accuracy of future AI-assisted development.\n\n## Technical Debt & Known Issues\n\n*   **Remote Config Memory & Concurrency**:\n    *   `setCustomSignals:` also strongly captures `self` via `self->_settings.customSignals`.\n    *   There is a deadlock hazard in `configValueForKey:` due to synchronous dispatch to `_queue` which then dispatches asynchronously back to `_queue` via `callListeners:`.\n    *   `RCNConfigExperiment` has data race risks on `_experimentPayloads` and other mutable collections as they are mutated from different queues (e.g., `loadExperimentFromTable` vs `updateExperimentsWithResponse:`).\n    *   In `RCNConfigExperiment`, `updateActiveExperimentsInDB` performs asynchronous DB operations. Subsequent code in `updateExperimentsWithHandler:` (such as `updateExperimentsWithServiceOrigin:`) is not guaranteed to execute after the DB updates complete, leading to a potential race condition.\n\n## AI Subagent Personas\n\nThe following personas are defined for use by AI orchestrators (like the\n`autonomous-tdd-loop` skill).\n\n### Objective Code Verifier\n**Role:** Objective Code Verifier\n**Prompt Guidelines:** Your job is strictly to run builds and test suites. Use\nthe `./scripts/style.sh` for formatting checks, and\n`./scripts/setup_spm_tests.sh` followed by `xcodebuild` (or `pod gen` and\n`xcodebuild` for CocoaPods) as dictated by the orchestrator. You are to report\na binary pass/fail result along with the specific error output if a failure\noccurs. Do not attempt to fix the code yourself unless specifically instructed.\n\n### Rigorous Code Reviewer\n**Role:** Rigorous Code Reviewer\n**Prompt Guidelines:** Your job is to perform a subjective, rigorous code\nreview on proposed changes. Focus on concurrency (Swift 6 strict concurrency),\nmemory management (retain cycles, etc.), API design (following\n`docs/firebase-api-guidelines.md`), and overall architectural consistency with\nthe rest of the Firebase iOS SDK. You should enforce best practices and flag\nany issues for the main agent to address.\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/firebase/firebase-ios-sdk/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}