vybekiit 0.7.28 → 0.7.32

package/dist/global-skills/firebase-crashlytics/references/android_setup.md

@@ -1,155 +1,183 @@
-# Firebase Crashlytics Android Setup Guide
-
-Important references:
-
-- Refer to the `firebase-basics` skills, particularly those for project and app
-  setup, before proceeding.
-
-## Project and App Setup
-
-Before you begin, ensure you have the following. If a `google-services.json`
-file is present, then use that Firebase project and app. Otherwise you may need
-to create them.
-
-- **Firebase CLI**: Installed and logged in (see `firebase-basics`).
-- **Firebase Project**: Created via
-  `npx -y firebase-tools@latest projects:create` (see `firebase-basics`).
-- **Firebase App**: Created via
-  `npx -y firebase-tools@latest apps:create ANDROID <display-name> --package-name=<package-name>`
-
-The `google-services.json` file must be present in the Android app's module
-directory. If missing, get the config using the Firebase CLI:
-`npx -y firebase-tools@latest apps:sdkconfig ANDROID <App-ID>`.
-
-## Add Dependencies to Gradle Build
-
-These changes are made to your Android project's Gradle files.
+# Firebase Crashlytics - Android Setup Guide (Kotlin)
+
+This guide describes the SDK setup and basic usage patterns for
+Firebase Crashlytics in an Android app using
+Kotlin DSL (`build.gradle.kts`) and Kotlin code.
+
+## Prerequisites
+
+IMPORTANT: Before specifically working with Firebase Crashlytics, make sure
+to use the skill and reference `firebase_basics/references/android_setup` to
+ensure the following is done.
+
+- The Firebase CLI is available and authenticated.
+- An Android project exists and is registered with a Firebase Project.
+- The Android project has a Firebase config file (`google-services.json`) and
+  the Google services Gradle plugin (`google-services`).
+
+______________________________________________________________________
+
+## 1. Add dependencies to Gradle build files
+
+> [!IMPORTANT] **[AGENT] RESOLVING THE SDK & PLUGIN VERSIONS DETERMINISTICALLY**
+> Never guess or hardcode a memorized out-of-date SDK or plugin version.
+> Before adding dependencies, you MUST query the latest available versions
+> directly from the Google Maven Repository:
+>
+> ```bash
+> # Find the latest Firebase Android BoM version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-bom/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+>
+> # Find the latest Crashlytics Gradle plugin version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-crashlytics-gradle/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+>
+> # Find the latest firebase-crashlytics version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-crashlytics/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+>
+> # Find the latest firebase-crashlytics-ndk version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-crashlytics-ndk/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+> ```
+>
+> If the dependency is already declared, fetch the exact resolved version
+> currently active in the workspace's build graph:
+>
+> ```bash
+> ./gradlew -q :app:dependencyInsight --dependency firebase-crashlytics --configuration releaseRuntimeClasspath
+> ```
+
+These changes are made to the Android project's Gradle files.
 
 ### Project-level `build.gradle.kts` (`<project>/build.gradle.kts`)
 
-Add the latest version of the Crashlytics Gradle plugin to the `plugins` block.
-Fetch the
-[latest version from the Google Maven repository](https://maven.google.com/web/index.html?q=firebase-crashlytics-gradle#com.google.firebase:firebase-crashlytics-gradle)
-before adding this.
+Add the latest version of the Crashlytics Gradle plugin to the `plugins` block:
 
 ```kotlin
 plugins {
     // ... other plugins
+
+    // [AGENT] Fetch the latest resolved version using the Gradle command above
     id("com.google.firebase.crashlytics") version "<latest_plugin_version>" apply false
 }
 ```
 
-### App-level `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)
+### Module (app-level) `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)
+
+1.  Add the Crashlytics Gradle plugin to the `plugins` block:
 
-1. Add the Crashlytics plugin to the `plugins` block:
+    ```kotlin
+    plugins {
+        // ... other plugins
 
-   ```kotlin
-   plugins {
-       // ... other plugins
-       id("com.google.firebase.crashlytics")
-   }
-   ```
+        id("com.google.firebase.crashlytics")
+    }
+    ```
 
-1. Add the Firebase Crashlytics dependency to the `dependencies` block. It is
-   recommended to use the Firebase Bill of Materials (BoM) to manage SDK
-   versions. Fetch the
-   [latest version from the Google Maven repository](https://maven.google.com/web/index.html?q=firebase-bom#com.google.firebase:firebase-bom)
-   before adding this.
+2.  Add the Firebase Crashlytics dependency to the `dependencies` block:
 
-   ```kotlin
-   dependencies {
-       // ... other dependencies
+    ```kotlin
+    dependencies {
+        // ... other dependencies
 
-       // Import the Firebase BoM
-       implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
+        // [AGENT] Fetch the latest resolved version using the Gradle command above
+        implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
 
-       // Add the dependencies for the Crashlytics and Analytics
-       implementation("com.google.firebase:firebase-crashlytics")
-       implementation("com.google.firebase:firebase-analytics")
-   }
-   ```
+        // Add the dependency for the Firebase Crashlytics library
+        // When using the BoM, don't specify versions in Firebase library dependencies
+        implementation("com.google.firebase:firebase-crashlytics")
+    }
+    ```
 
-## Follow up Steps
+______________________________________________________________________
 
-### Optional: Install the NDK SDK to capture native crashes
+## 2. *Optional:* Install the NDK SDK to capture native crashes
 
-If your app uses native code (C/C++), or includes a library with native code,
-you can configure Crashlytics to report native crashes.
+If the Android project uses native code (C/C++), or includes a library with
+native code, configure Crashlytics to report native crashes.
 
 App-level `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)
 
-1. Add the `firebase-crashlytics-ndk` dependency:
-
-   ```kotlin
-   dependencies {
-       // ... other dependencies
-       implementation("com.google.firebase:firebase-crashlytics-ndk")
-   }
-   ```
-
-1. Enable the `nativeSymbolUpload` flag in your `buildTypes` configuration. This
-   will automatically upload symbol files for your native code, which are
-   required to symbolicate native crash reports.
-
-   ```kotlin
-   import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension
-
-   android {
-       // ... other config
-       buildTypes {
-           getByName("release") {
-               // ...
-               configure<CrashlyticsExtension> {
-                   nativeSymbolUploadEnabled = true
-               }
-           }
-       }
-   }
-   ```
-
-After these changes, Crashlytics will automatically report crashes in your app's
+1.  Add the `firebase-crashlytics-ndk` dependency:
+
+    ```kotlin
+    dependencies {
+        // ... other dependencies
+
+        // [AGENT] Fetch the latest resolved version using the Gradle command above
+        implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
+
+        // Add the dependency for the Firebase Crashlytics NDK library
+        // When using the BoM, don't specify versions in Firebase library dependencies
+        implementation("com.google.firebase:firebase-crashlytics-ndk")
+    }
+    ```
+
+2.  Enable the `nativeSymbolUpload` flag in the `buildTypes` configuration.
+    This will automatically upload symbol files for the native code, which are
+    required to symbolicate native crash reports.
+
+    ```kotlin
+    android {
+        // ... other config
+        buildTypes {
+            getByName("release") {
+                // ...
+                firebaseCrashlytics {
+                    nativeSymbolUploadEnabled = true
+                }
+            }
+        }
+    }
+    ```
+
+After these changes, Crashlytics will automatically report crashes in the app's
 native code.
 
-### Required: Force a Test Crash
+______________________________________________________________________
+
+## 3. *Required:* Force a test crash
+
+To verify that Crashlytics is correctly set up in the Android project, force a
+test crash in the app.
+
+1.  Add code to the main activity (e.g., in `onCreate`) to trigger a crash a
+    few seconds after app startup:
 
-To verify that Crashlytics is correctly installed, you need to force a test
-crash in the app.
+    ```kotlin
+    import android.os.Handler
+    import android.os.Looper
 
-1. Add code to your main activity (e.g., in `onCreate`) to trigger a crash a few
-   seconds after app startup:
+    // ... in the Activity's onCreate method or similar startup logic
+    Handler(Looper.getMainLooper()).postDelayed({
+        throw RuntimeException("Test Crash") // Force a crash after 3 seconds
+    }, 3000)
+    ```
 
-   ```kotlin
-   import android.os.Handler
-   import android.os.Looper
+2.  Run the app on a device or emulator. The app should crash after a short
+    delay.
 
-   // ... in your Activity's onCreate method or similar startup logic
-   Handler(Looper.getMainLooper()).postDelayed({
-       throw RuntimeException("Test Crash") // Force a crash after 3 seconds
-   }, 3000)
-   ```
+3.  Restart the app. The Crashlytics SDK will send the crash report to Firebase
+    on the next app launch.
 
-1. Run your app on a device or emulator. The app should crash after a short
-   delay.
+4.  After a few minutes, the crash should be available in Firebase.
 
-1. Restart the app. The Crashlytics SDK will send the crash report to Firebase
-   on the next app launch.
+    - If the Firebase MCP server is installed, use the `get_report` tool to
+      verify that a crash was received.
+    - As a fallback, tell the human user to go to the Crashlytics dashboard in
+      the Firebase console to verify the new crash report. Provide the human
+      user with a constructed Firebase console URL using the Firebase PROJECT_ID
+      and the PACKAGE_NAME:
+      `https://console.firebase.google.com/u/0/project/PROJECT_ID/crashlytics/app/android:PACKAGE_NAME/issues`
 
-1. After a few minutes, the crash should be available in the Firebase console.
-   Go to **DevOps & Engagement** > **Crashlytics** to view your dashboard and
-   crash reports.
+5.  After verifying that Firebase has received the crash report -- either using
+    the `get_report` tool or manually viewing it in the Firebase console --
+    remove the code that triggers the test crash.
 
-- If the Firebase MCP server is installed, use the `get_report` tool to check
-  that a crash was received.
-- As a fallback, visit the Crashlytics dashboard in the Firebase console to see
-  the new crash report.
+______________________________________________________________________
 
-5. After verifying that Firebase has received the crash report - either using
-   the `get_report` tool or manually viewing it in the Firebase console - remove
-   the code from step 1 that triggers the crash. This prevents the application
-   from always crashing on start up after a delay.
+## Optional additional steps
 
-### Optional: Add custom debugging information
+### Add custom debugging information
 
-Customize reports to help you better understand what's happening in your app and
-the circumstances around events reported to Crashlytics. See
-[Customize Crash Reports for Android](https://firebase.google.com/docs/crashlytics/android/customize-crash-reports.md).
+Customize reports to help better understand what's happening in the app and the
+circumstances around events reported to Crashlytics. See
+https://firebase.google.com/docs/crashlytics/android/customize-crash-reports.md.txt.

package/dist/global-skills/firebase-data-connect/SKILL.md

@@ -3,6 +3,7 @@ name: firebase-data-connect
 description: Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely. Use when designing schemas with tables and relations, writing authorized queries and mutations, configuring real-time data updates, or generating type-safe SDKs. Use when you need a relational database with Firebase, or when the user mentions SQL Connect or Data Connect.
 metadata:
   category: Databases
+disable-model-invocation: true
 ---
 
 # Firebase SQL Connect

package/dist/global-skills/firebase-data-connect/reference/sdk_android.md

@@ -1,9 +1,21 @@
-# Android SDK
+# Firebase SQL Connect - Android Setup Guide (Kotlin)
 
-Consult this file when writing Android application code (Kotlin) that interacts
-with the SQL Connect backend.
+This guide describes the SDK setup and basic usage patterns for
+Firebase SQL Connect in an Android app using
+Kotlin DSL (`build.gradle.kts`) and Kotlin code.
 
-### Best Practices for Agents
+## Prerequisites
+
+IMPORTANT: Before specifically working with Firebase SQL Connect, make sure
+to use the skill and reference `firebase_basics/references/android_setup` to
+ensure the following is done.
+
+- The Firebase CLI is available and authenticated.
+- An Android project exists and is registered with a Firebase Project.
+- The Android project has a Firebase config file (`google-services.json`) and
+  the Google services Gradle plugin (`google-services`).
+
+## Best practices for agents working with Firebase SQL Connect
 
 - **Understand Operation Storage**: SQL Connect queries and mutations are stored
   on the server like Cloud Functions. **Whenever you update operations, you must
@@ -19,26 +31,66 @@ with the SQL Connect backend.
 - **Leverage Coroutines**: Call `.execute()` within a coroutine scope for
   asynchronous operations.
 
-### Dependencies (build.gradle.kts)
+______________________________________________________________________
+
+## 1. Add dependencies to Gradle build files
+
+> [!IMPORTANT] **[AGENT] RESOLVING THE SDK VERSION DETERMINISTICALLY**
+> Never guess or hardcode a memorized out-of-date SDK or plugin version.
+> Before adding dependencies, you MUST query the latest available versions
+> directly from the Google Maven Repository:
+>
+> ```bash
+> # Find the latest Firebase Android BoM version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-bom/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+>
+> # Find the latest firebase-dataconnect version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-dataconnect/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+> ```
+>
+> If the dependency is already declared, fetch the exact resolved version
+> currently active in the workspace's build graph:
+>
+> ```bash
+> ./gradlew -q :app:dependencyInsight --dependency firebase-dataconnect --configuration releaseRuntimeClasspath
+> ```
+
+In the **module (app-level)** `build.gradle.kts` (usually
+`<project>/<app-module>/build.gradle.kts`), add the
+Kotlin serialization plugin and the dependency for Firebase SQL Connect:
+
+1.  Add the Kotlin serialization plugin to the `plugins` block:
+
+    ```kotlin
+    plugins {
+        // ... other plugins
+        kotlin("plugin.serialization") version "1.8.22" // Must match Kotlin version
+    }
+    ```
 
-Ensure you have the Kotlin Serialization plugin and standard SQL Connect
-dependencies:
+2.  Add the required Firebase SQL Connect dependencies to the `dependencies`
+    block:
 
-```kotlin
-plugins {
-    kotlin("plugin.serialization") version "1.8.22" // Must match Kotlin version
-}
+    ```kotlin
+    dependencies {
+        // ... other dependencies
 
-dependencies {
-    // [AGENT] Fetch the latest available BoM version from https://firebase.google.com/support/release-notes/android before adding this
-    implementation(platform("com.google.firebase:firebase-bom:34.12.0"))
-    implementation("com.google.firebase:firebase-dataconnect")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
-    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
-}
-```
+        // [AGENT] Fetch the latest resolved version using the Gradle command above
+        implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
+
+        // Add the dependency for the Firebase SQL Connect library
+        // When using the BoM, don't specify versions in Firebase library dependencies
+        implementation("com.google.firebase:firebase-dataconnect")
+
+        // Add additional required dependencies
+        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
+        implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
+    }
+    ```
 
-### Initialization
+______________________________________________________________________
+
+## 2. Initialize
 
 Retrieve the generated connector instance:
 
@@ -54,9 +106,13 @@ connector.dataConnect.useEmulator()
 // connector.dataConnect.useEmulator(port = 9999)
 ```
 
-### Calling Operations
+______________________________________________________________________
+
+## 3. Work with SQL Connect
+
+### Calling operations
 
-#### Basic Query
+#### Basic query
 
 ```kotlin
 val result = connector.listMovies.execute()
@@ -76,7 +132,7 @@ val newMovie = connector.createMovie.execute(
 )
 ```
 
-### Resilient Enum Handling
+### Resilient enum handling
 
 Unwrap the `EnumValue` to handle known and unknown cases safely.
 
@@ -91,7 +147,7 @@ result.data.movies.forEach { movie ->
 }
 ```
 
-### Client-Side Caching
+### Client-side caching
 
 Enable caching in `connector.yaml` to reduce requests and support offline
 scenarios.
@@ -113,7 +169,7 @@ val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)
 val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)
 ```
 
-### Data Type Mapping Reference
+### Data type mapping reference
 
 - GraphQL `String` -> Kotlin `String`
 - GraphQL `Int` -> Kotlin `Int` (32-bit)

package/dist/global-skills/firebase-firestore/SKILL.md

@@ -5,6 +5,7 @@ description: >-
 compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`.
 metadata:
   category: Databases
+disable-model-invocation: true
 ---
 
 # Cloud Firestore Database and Operations

package/dist/global-skills/firebase-firestore/references/enterprise/android_sdk_usage.md

@@ -1,25 +1,45 @@
-# Android SDK Usage (Enterprise Native Mode)
+# Cloud Firestore (Enterprise edition) - Android Setup Guide (Kotlin)
 
-This guide covers the Firestore Android SDK (Kotlin) setup and usage patterns
-optimized for Firestore Enterprise edition in Native mode.
+This guide describes the SDK setup and basic usage patterns for
+Cloud Firestore (Enterprise edition in Native mode) in an Android app using
+Kotlin DSL (`build.gradle.kts`) and Kotlin code.
+
+## Prerequisites
+
+IMPORTANT: Before specifically working with Cloud Firestore, make sure
+to use the skill and reference `firebase_basics/references/android_setup` to
+ensure the following is done.
+
+- The Firebase CLI is available and authenticated.
+- An Android project exists and is registered with a Firebase Project.
+- The Android project has a Firebase config file (`google-services.json`) and
+  the Google services Gradle plugin (`google-services`).
 
 ______________________________________________________________________
 
-## 1. Initialization
+## 1. Provision Firestore
+
+Follow the instructions in
+`firebase_firestore/references/enterprise/provisioning` to do the following:
+
+- Provision a Firestore instance (Enterprise edition in Native mode)
+- Create or append a `firebase.json` file
+- Create a `firestore.rules` file
+- Create a `firestore.indexes.json` file
+- Deploy database, rules, and indexes
+- Run Firestore locally for development and testing
 
-### Add Dependencies
+______________________________________________________________________
 
-In your module-level `build.gradle.kts` (usually `app/build.gradle.kts`), add
-the Firebase Kotlin Bill of Materials (BoM) and the dependency for Cloud
-Firestore:
+## 2. Add dependencies to Gradle build files
 
-> [!IMPORTANT] **[AGENT] RESOLVING THE RESOLVED SDK VERSION DETERMINISTICALLY**
-> Never guess or hardcode a memorized out-of-date SDK version. Before adding
-> dependencies, you MUST query the latest available versions directly from the
-> Google Maven Repository:
+> [!IMPORTANT] **[AGENT] RESOLVING THE SDK VERSION DETERMINISTICALLY**
+> Never guess or hardcode a memorized out-of-date SDK or plugin version.
+> Before adding dependencies, you MUST query the latest available versions
+> directly from the Google Maven Repository:
 >
 > ```bash
-> # Find the latest Firebase BoM version
+> # Find the latest Firebase Android BoM version
 > curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-bom/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
 >
 > # Find the latest firebase-firestore version
@@ -33,20 +53,26 @@ Firestore:
 > ./gradlew -q :app:dependencyInsight --dependency firebase-firestore --configuration releaseRuntimeClasspath
 > ```
 
+In the **module (app-level)** `build.gradle.kts` (usually
+`<project>/<app-module>/build.gradle.kts`), add the dependency for
+Cloud Firestore:
+
 ```kotlin
 dependencies {
     // [AGENT] Fetch the latest resolved version using the Gradle command above
     implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
 
     // Add the dependency for the Cloud Firestore library
-    // When using the BoM, you don't specify versions in Firebase library dependencies
+    // When using the BoM, don't specify versions in Firebase library dependencies
     implementation("com.google.firebase:firebase-firestore")
 }
 ```
 
-### Initialize Firestore
+______________________________________________________________________
 
-Initialize the `FirebaseFirestore` instance in your ComponentActivity (Jetpack
+## 3. Initialize Firestore
+
+Initialize the `FirebaseFirestore` instance in your `ComponentActivity` (Jetpack
 Compose) or standard Activity/Fragment:
 
 ```kotlin
@@ -63,7 +89,7 @@ class MainActivity : ComponentActivity() {
         super.onCreate(savedInstanceState)
         // Initialize the Firestore instance
         val db = FirebaseFirestore.getInstance("<database-name>")
-        
+
         setContent {
             MaterialTheme {
                 Text("Firestore initialized!")
@@ -75,7 +101,7 @@ class MainActivity : ComponentActivity() {
 
 ______________________________________________________________________
 
-## 2. Decision Framework: Mandatory Pipeline Architecture
+## 4. Decision framework: Mandatory pipeline architecture
 
 > [!CRITICAL] **MANDATORY PIPELINE ARCHITECTURE (ZERO TOLERANCE)** You are
 > strictly forbidden from using standard collection queries (e.g.,
@@ -85,34 +111,34 @@ ______________________________________________________________________
 > Server-side execution via pipelines is the superior, non-negotiable core
 > architecture for Enterprise instances.
 
-### Strict Rules & Accountability
-
-1. **Mandatory Execution Engine**: Every repository lookup requiring related
-   data mapping, textual relevance scoring, or multi-document counting MUST be
-   authored natively using the server-side `db.pipeline()` API.
-1. **Required Proof of Use**: In your task execution summaries, you MUST
-   explicitly highlight the exact pipeline stages (`.define()`, `.addFields()`,
-   `.search()`, `.aggregate()`) integrated into your primary data layer return
-   paths. Failure to implement pipelines natively constitutes an immediate
-   violation of instructions.
-1. **Check API References**:
-   - **Locate**: Locate the standard Maven sources JAR (`-sources.jar`)
-     corresponding to the resolved `firebase-firestore` dependency version
-     inside your local Gradle or Maven dependency cache.
-   - **Extract Once**: Extract the documentation files `pipeline.docs.txt` and
-     `expressions.docs.txt` from the root directory of that `-sources.jar`
-     archive into a temporary workspace scratch directory of your choice.
-   - **Read & Reference**:
-     - **Read** the extracted `pipeline.docs.txt` once fully to understand core
-       pipeline structure and stage capabilities.
-     - **Reference** the extracted `expressions.docs.txt` on-demand for specific
-       function overloads and parameters.
+### Strict rules & accountability
+
+1.  **Mandatory Execution Engine**: Every repository lookup requiring related
+    data mapping, textual relevance scoring, or multi-document counting MUST be
+    authored natively using the server-side `db.pipeline()` API.
+1.  **Required Proof of Use**: In your task execution summaries, you MUST
+    explicitly highlight the exact pipeline stages (`.define()`, `.addFields()`,
+    `.search()`, `.aggregate()`) integrated into your primary data layer return
+    paths. Failure to implement pipelines natively constitutes an immediate
+    violation of instructions.
+1.  **Check API References**:
+    - **Locate**: Locate the standard Maven sources JAR (`-sources.jar`)
+      corresponding to the resolved `firebase-firestore` dependency version
+      inside your local Gradle or Maven dependency cache.
+    - **Extract Once**: Extract the documentation files `pipeline.docs.txt` and
+      `expressions.docs.txt` from the root directory of that `-sources.jar`
+      archive into a temporary workspace scratch directory of your choice.
+    - **Read & Reference**:
+      - **Read** the extracted `pipeline.docs.txt` once fully to understand core
+        pipeline structure and stage capabilities.
+      - **Reference** the extracted `expressions.docs.txt` on-demand for
+        specific function overloads and parameters.
 
 ______________________________________________________________________
 
-## 3. Pipeline Examples
+## 5. Pipeline examples
 
-### Relational Joins Pattern
+### Relational joins pattern
 
 When querying related data (e.g., articles and their author profiles), perform
 the join at the database level via pipeline stages instead of executing multiple
@@ -142,7 +168,7 @@ val articlesWithAuthProfile = db.pipeline().collection("articles")
     )
 ```
 
-### Full-Text Search
+### Full-text search
 
 Leverage the database-native `.search()` stage within your pipelines to run
 high-performance text query matches on the database level.
@@ -164,7 +190,7 @@ val searchPipeline = db.pipeline()
 
 ______________________________________________________________________
 
-## 4. Real-Time Listener & Document Operations
+## 6. Real-time listener & document operations
 
 When real-time data sync or transaction-based document mutations are strictly
 required by application specifications, write clean operations as shown in this