vybekiit 0.7.4 → 0.7.7

package/dist/global-skills/expo-upgrade/SKILL.md

@@ -27,6 +27,8 @@ npx expo install expo@next --fix  # install beta
 
 ## Step-by-Step Upgrade Process
 
+> If upgrading from SDK 55 or earlier, skip SDK 56 and upgrade directly to SDK 57. Don't use `expo@57.0.8` or below. SDK 55 with Hermes V1 enabled, SDK 56, and older SDK 57 releases contain a Hermes V1 memory regression that can drastically increase memory usage when using `react-native-worklets` or `react-native-reanimated`.
+
 1. Upgrade Expo and dependencies
 
 ```bash
@@ -75,6 +77,7 @@ These steps only apply when `ios/` and/or `android/` directories exist in the pr
 ## Housekeeping
 
 - Review release notes for the target SDK version at https://expo.dev/changelog
+- Update versioned docs links in agent instruction files (`AGENTS.md`). The default template links to `https://docs.expo.dev/versions/v<version>/`. Search for `docs.expo.dev/versions/` and bump each link to the new SDK version.
 - If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
 - Enable React Compiler in SDK 54+ by adding `"experiments": { "reactCompiler": true }` to app.json — it's stable and recommended
 - Delete sdkVersion from `app.json` to let Expo manage it automatically
@@ -106,6 +109,7 @@ Check if package.json has excluded packages:
 ```
 
 Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.
+
 ## Removing patches
 
 Check if there are any outdated patches in the `patches/` directory. Remove them if they are no longer needed.
@@ -127,8 +131,18 @@ Remove redundant metro config options:
 
 ## Hermes engine v1
 
-Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting `useHermesV1: true` in the `expo-build-properties` config plugin, and may require a specific version of the `hermes-compiler` npm package. Hermes v1 will become a default in some future SDK release.
+Hermes V1 is the default on SDK 56 and later. SDK 55 apps using Hermes V1, all SDK 56 apps, and SDK 57 apps before `expo@57.0.9` may encounter a memory regression when importing `react-native-worklets` or `react-native-reanimated`. Upgrade directly to SDK 57 and `expo@57.0.9` or later. Do not recommend Worklets Bundle Mode as a production workaround; it is unsupported and experimental and may not work as expected.
+
+Do not guide users to opt in to or out of Hermes V1. Changing the Hermes version from the SDK default is unsupported and has significant build and dependency-management caveats.
 
 ## New Architecture
 
 The new architecture is enabled by default, the app.json field `"newArchEnabled": true` is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/expo-web-to-native/SKILL.md

@@ -81,3 +81,11 @@ Pass on parity of **content and behavior** — not pixels: a nativized screen sh
 - [`./references/verify-on-device.md`](./references/verify-on-device.md) — the two-agent parity recipe: drive the web app (browser agent) and the native app (argent), open the same route, compare.
 - [`./references/run-as-goal.md`](./references/run-as-goal.md) — a ready-shaped, migration-specific goal objective for driving step 4 unattended (re-reads this skill each iteration).
 - [Expo — From Web to Native with React](https://expo.dev/blog/from-web-to-native-with-react) — the canonical guide this skill operationalizes.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-web-to-native" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/extension-to-functions-codebase/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: extension-to-functions-codebase
+description: Skill for converting an installed Firebase Extension (or extension source) into a standalone Cloud Functions for Firebase codebase or publishable npm package, including V1 to V2 trigger upgrades, lifecycle hooks, and declarative security
+metadata:
+  category: Serverless
+---
+
+# Extension to Functions Codebase & npm Package Migration
+
+## Overview
+
+Migrates a Firebase Extension into either:
+
+1. **A local Cloud Functions codebase** (`functions/src/` for app integration).
+1. **A publishable npm package** (reusable open-source package exporting V2
+   functions).
+
+Leverages native Cloud Functions features (declarative IAM, Parameterized
+Config, SDK Lifecycle Hooks) and modernizes 1st Gen triggers to 2nd Gen using
+the Destructuring Compatibility Shim.
+
+______________________________________________________________________
+
+## Target Migration Workflows
+
+- **Target A: Local Functions Codebase** (End-User App Integration)
+
+  - Output: Code under `functions/src/`. Config in `.env`.
+  - Deployment: `firebase deploy --only functions`.
+
+- **Target B: Publishable npm Package / Shareable Package**
+
+  - Output: Reusable npm package exporting V2 functions.
+  - Configuration: `package.json` specifying `exports` map,
+    `engines: { "node": ">=22" }`, and
+    `peerDependencies: { "firebase-functions": ">=6.0.0" }`.
+  - Usage: Consumers install package and re-export functions in `index.ts`
+    (`export * from "<package-name>"`).
+
+______________________________________________________________________
+
+## Core Rules & Constraints
+
+### 1. Declarative IAM & APIs (Zero-Local-Overhead)
+
+Use native SDK declarations instead of manual `gcloud` scripts or console
+instructions:
+
+- Use `requiresRole("roles/...")` for required GCP IAM permissions.
+- Use `requiresAPI("service.googleapis.com", "Description")` for Google APIs.
+
+### 2. Global Parameter Access Restriction
+
+- **Never call `.value()` at top-level module load scope.**
+- Initialize global SDK instances inside `onInit()` or lazy getters:
+  ```typescript
+  import { defineString } from "firebase-functions/params";
+  import { onInit } from "firebase-functions/v2";
+
+  const dataset = defineString("DATASET_ID");
+  let client: BigQuery;
+
+  onInit(() => {
+    client = new BigQuery({ datasetId: dataset.value() });
+  });
+  ```
+
+### 3. V2 Concurrency & Cost Parity
+
+V2 enables concurrency (up to 80 requests). To preserve V1 single-concurrency
+pricing, set `cpu: "gcf_gen1"`.
+
+______________________________________________________________________
+
+## Step-by-Step Migration Execution
+
+### Step 1: Inventory Extension Resources
+
+1. **`extension.yaml`**:
+   - `params` → `defineString`, `defineInt`, `defineBoolean`, `defineSecret`.
+   - `apis` → `requiresAPI(...)`.
+   - `roles` → `requiresRole(...)`.
+   - `lifecycleEvents` → `afterFirstDeploy` & `afterRedeploy`.
+   - `resources` → Upgrade 1st Gen triggers to 2nd Gen (`onDocumentWritten`,
+     `onTaskDispatched`, `onRequest`).
+1. **Files & Scripts**: Preserve devDependencies, test framework (`jest`), and
+   test scripts.
+
+### Step 2: Configure `package.json`
+
+- Set `name: "<package-name>"`, `engines: { "node": ">=22" }`.
+- Set `peerDependencies`:
+  ```json
+  "peerDependencies": {
+    "firebase-admin": "^11.0.0 || ^12.0.0",
+    "firebase-functions": ">=6.0.0"
+  }
+  ```
+- Configure `exports` map targeting ESM/CommonJS and TypeScript declarations
+  (`lib/index.js`, `lib/index.d.ts`).
+
+### Step 3: Upgrade Triggers from V1 to V2
+
+- Firestore: Use `onDocumentWritten` from `firebase-functions/v2/firestore`.
+- Tasks: Use `onTaskDispatched` from `firebase-functions/v2/tasks`. Remove
+  `EXT_INSTANCE_ID` when enqueueing tasks.
+- HTTP: Use `onRequest` from `firebase-functions/v2/https`.
+- Apply Destructuring Compatibility Shim (`{ change, context }`,
+  `{ snapshot, context }`) where legacy 1st Gen handlers expect
+  `(change, context)`.
+
+### Step 4: Convert Lifecycle Events
+
+Map extension lifecycle events to SDK lifecycle hooks in `src/index.ts`:
+
+- `onInstall` → `afterFirstDeploy({ task: { function: "initTask" } })`
+- `onUpdate` / `onConfigure` →
+  `afterRedeploy({ task: { function: "setupTask" } })`
+
+### Step 5: Package README & Export Instructions
+
+Generate `README.md` containing:
+
+1. Installation instructions (`npm install`).
+1. Re-export snippet (`export * from "<package-name>"`).
+1. Parameterized Configuration `.env` reference table.
+1. What Changed (Extension vs Package) comparison table.
+
+_Reminder: NEVER execute `npm publish`._

package/dist/global-skills/extension-to-functions-codebase/references/configuration-migration.md

@@ -0,0 +1,161 @@
+# Migrating Runtime Configurations (runWith)
+
+In Cloud Functions for Firebase V1 (`firebase-functions/v1`), you configured
+runtime settings like memory, timeout, and service accounts using `.runWith()`.
+In V2 (`firebase-functions/v2`), `.runWith()` is removed and replaced by a more
+flexible options system.
+
+You can configure V2 functions in two ways: **Per-Function** (passing an options
+object directly to the trigger) or **Globally** (`setGlobalOptions` at the top
+of a file).
+
+______________________________________________________________________
+
+## 1. Per-Function Configuration
+
+Pass the configuration options object as the **first argument** to the V2
+trigger function. Per-function options always override any global defaults.
+
+### V1 Legacy
+
+```typescript
+import * as functions from "firebase-functions";
+
+export const processOrder = functions
+  .runWith({ memory: "2GB" })
+  .pubsub.topic("orders")
+  .onPublish((message, context) => { ... });
+```
+
+### V2 Modern Equivalent
+
+```typescript
+import { onMessagePublished } from "firebase-functions/v2/pubsub";
+
+export const processOrder = onMessagePublished(
+  {
+    topic: "orders",
+    memory: "2GiB", // Options passed as the first argument!
+  },
+  ({ message, context }) => { ... } // Destructuring shim pattern
+);
+```
+
+> [!TIP] **Memory Unit Caveat**: V1 accepted `"1GB"`. V2 types strongly prefer
+> IEC units like `"1GiB"`, `"2GiB"`, etc.
+
+______________________________________________________________________
+
+## 2. Global Configuration (`setGlobalOptions`)
+
+Use `setGlobalOptions` at the top of your file when all or most functions in
+that file share the exact same runtime requirements (e.g. identical region,
+memory allocation, timeout, or service account). Individual functions can still
+override specific settings by declaring per-function options.
+
+### V1 Legacy
+
+```typescript
+import * as functions from "firebase-functions";
+
+export const myFn = functions
+  .runWith({
+    memory: "1GB",
+    timeoutSeconds: 120,
+    serviceAccount: "custom-sa@my-project.iam.gserviceaccount.com",
+  })
+  .https.onRequest((req, res) => { ... });
+```
+
+### V2 Modern Equivalent
+
+```typescript
+import { setGlobalOptions } from "firebase-functions/v2";
+import { onRequest } from "firebase-functions/v2/https";
+
+// Set global defaults for all functions defined after this call in this file
+setGlobalOptions({
+  memory: "1GiB", // Note: GiB instead of GB is preferred in V2 types
+  timeoutSeconds: 120,
+  serviceAccount: "custom-sa@my-project.iam.gserviceaccount.com",
+});
+
+export const myFn = onRequest((req, res) => { ... });
+```
+
+______________________________________________________________________
+
+## Common Property Translations
+
+| V1 Property                  | V2 Property                  | Notes                                                           |
+| :--------------------------- | :--------------------------- | :-------------------------------------------------------------- |
+| `memory`                     | `memory`                     | Use `"1GiB"` instead of `"1GB"`.                                |
+| `timeoutSeconds`             | `timeoutSeconds`             | Same.                                                           |
+| `ingressSettings`            | `ingressSettings`            | Same.                                                           |
+| `vpcConnector`               | `vpcConnector`               | Same.                                                           |
+| `vpcConnectorEgressSettings` | `vpcConnectorEgressSettings` | Same.                                                           |
+| `serviceAccount`             | `serviceAccount`             | Same.                                                           |
+| `secrets`                    | `secrets`                    | Same.                                                           |
+| `failurePolicy`              | `retry`                      | Renamed to boolean `retry: true/false` in V2 Eventarc triggers. |
+
+______________________________________________________________________
+
+## 3. Migrating Environment Configurations (`functions.config()`)
+
+In V1, you used `functions.config()` to access environment configuration. In V2,
+this is replaced by **Parameterized Configuration**.
+
+### Deterministic Rules for Migration
+
+Follow these rules to ensure a deterministic and safe migration:
+
+#### Typing & Exports
+
+- **Numbers**: If the value is used as a number, use `defineInt` or
+  `defineNumber`.
+- **Secrets**: If the key contains "KEY", "SECRET", "TOKEN", or "PASSWORD", use
+  `defineSecret()` or `defineJsonSecret()`.
+  - *Note*: Secrets MUST be explicitly bound to the function that uses them in
+    the options object (e.g., `{ secrets: [myKey, myJsonSecret] }`). Both
+    `SecretParam` and `JsonSecretParam` are supported in the `secrets` array.
+- **Lists**: Use `defineList` for comma-separated lists.
+- **JSON**: Use `defineJSON` for JSON strings.
+- **Buckets**: If the param is a storage bucket, set `input: { text: {} }` or
+  bucket selector.
+- **Input Validation**: Use `nonEmpty: true` inside `input.text` or
+  `input.multiSelect` to enforce non-empty parameter input during CLI prompting
+  (e.g. `defineString("PARAM", { input: { text: { nonEmpty: true } } })`).
+- **Type Annotations**: Import parameter types directly from
+  `firebase-functions/params` (e.g.
+  `import type { StringParam, SecretParam, JsonSecretParam, IntParam } from "firebase-functions/params"`).
+
+#### Initialization & Scope
+
+- **Global Initialization**: If a variable was initialized globally in V1 (e.g.,
+  `const client = new Client(functions.config().key)`), you must split it to
+  have declaration at global scope and initialization inside `onInit`:
+  ```typescript
+  import { onInit } from "firebase-functions/v2";
+
+  const myKey = defineSecret("MY_KEY");
+  let client: Client;
+
+  onInit(() => {
+    client = new Client(myKey.value());
+  });
+  ```
+
+#### Advanced Interpolation & Logic
+
+- **String Interpolation**: Use the `expr` tagged template literal from
+  `firebase-functions/params` (e.g., `` `expr`every ${period} days` ``) instead
+  of standard template literals when constructing dynamic strings with
+  parameters. Do NOT call `.value()` inside `expr`.
+- **Logic Operators**: Use expressions like
+  `projectID.equals('prod').thenElse(1, 0)` for logical operations instead of
+  ternary operators on `.value()`.
+
+#### Built-ins
+
+- Prefer built-in variables like `databaseURL`, `projectID`, `gcloudProject`,
+  `storageBucket` rather than defining new params for these values.

package/dist/global-skills/extension-to-functions-codebase/references/destructuring-shim.md

@@ -0,0 +1,122 @@
+# Architectural Deep Dive: Destructuring Compatibility Shim
+
+The Destructuring Compatibility Shim is a **Zero-Touch Logic Migration**
+pattern. It allows you to upgrade a function's infrastructure to V2 (and take
+advantage of GCF 2nd Gen runtimes) without rewriting any of your internal
+business logic.
+
+______________________________________________________________________
+
+## How it Works
+
+When you migrate a V1 function to V2, the signature changes from two parameters
+`(data, context)` to a single `CloudEvent` object.
+
+Instead of manually rewriting all usages of `context.params` or `message.json`
+inside the function, you use JavaScript's **Object Destructuring** in the
+signature.
+
+### Example Transformation
+
+#### Step 1: Legacy V1
+
+```typescript
+export const processOrder = functions.pubsub.topic("orders").onPublish((message, context) => {
+  const orderId = message.json.id;
+  console.log(`Processing order ${orderId} at ${context.timestamp}`);
+});
+```
+
+#### Step 2: Modern V2 + Shim
+
+We change the trigger to `onMessagePublished`, and instead of accepting `event`,
+we destructure `{ message, context }` directly:
+
+```typescript
+export const processOrder = onMessagePublished("orders", ({ message, context }) => {
+  const orderId = message.json.id; // Legacy logic remains untouched!
+  console.log(`Processing order ${orderId} at ${context.timestamp}`);
+});
+```
+
+### Why This Works
+
+The Firebase Functions SDK uses a utility called `addV1Compat` to attach these
+properties via **Lazy Getters** on the `CloudEvent` object for standard event
+triggers. When you attempt to destructure `{ message, context }` from the event,
+the SDK transparently maps the V2 event properties back into V1-compatible
+objects on the fly! This feature is available in modern V2 environments
+supported by the SDK.
+
+______________________________________________________________________
+
+## Provider Mapping Examples
+
+Here are the exact destructuring patterns for every supported V2 provider:
+
+### 1. Cloud Firestore
+
+- **Created / Deleted** triggers:
+  ```typescript
+  // V2: onDocumentCreated, onDocumentDeleted
+  export const processDoc = onDocumentCreated("users/{id}", ({ snapshot, context }) => { ... });
+  ```
+- **Updated / Written** triggers:
+  ```typescript
+  // V2: onDocumentUpdated, onDocumentWritten
+  export const processDoc = onDocumentUpdated("users/{id}", ({ change, context }) => { ... });
+  ```
+
+### 2. Cloud Storage
+
+- **All** triggers (`onObjectFinalized`, `onObjectDeleted`, `onObjectArchived`,
+  `onObjectMetadataUpdated`):
+  ```typescript
+  export const processFile = onObjectFinalized(({ object, context }) => { ... });
+  ```
+
+### 3. Realtime Database
+
+- **Created / Deleted** triggers:
+  ```typescript
+  export const processData = onValueCreated("/users/{id}", ({ snapshot, context }) => { ... });
+  ```
+- **Updated / Written** triggers:
+  ```typescript
+  export const processData = onValueWritten("/users/{id}", ({ change, context }) => { ... });
+  ```
+
+### 4. Remote Config
+
+- **Updated** triggers:
+  ```typescript
+  export const processConfig = onConfigUpdated(({ version, context }) => { ... });
+  ```
+
+______________________________________________________________________
+
+## Best Practices for AI Agents
+
+1. **Rely on the shim for complex logic.** When converting functions with
+   extensive or complex internal business logic, prefer using the destructuring
+   shim (`{ shimmedKey, context }`) by default to minimize risk and avoid
+   introducing subtle bugs.
+1. **Clean-room rewrites.** If the function body is very simple, or if the user
+   explicitly asks for a comprehensive code modernization/cleanup, you can ask
+   the user if they would prefer a full clean-room rewrite to native V2 event
+   properties.
+1. **Always type-check (`tsc`) after the rewrite.** If the types are wrong, the
+   shim might not be fully supported for that specific provider yet.
+1. **HTTPS Callables (Flattened Context)**: Unlike event triggers, Callables do
+   **not** use `V1Compat` or a `context` object. Instead, all context properties
+   are flattened onto the request object.
+   - **V1 Priority**: `(data, context) => { ... }`
+   - **V2 Equivalent**: `({ data, auth, app }) => { ... }`
+
+______________________________________________________________________
+
+## Related Migrations
+
+For a complete guide on migrating runtime options and `functions.config()` to V2
+Parameterized Configuration, refer to
+[configuration-migration.md](configuration-migration.md).

package/dist/global-skills/extension-to-functions-codebase/references/signature-mapping.md

@@ -0,0 +1,84 @@
+# Firebase Functions V1 vs V2 Signature Mapping
+
+This reference maps legacy V1 functions to their modern V2 equivalents. When
+using the compatibility shim, you can destructure the V2 event object using the
+exact parameter names from the legacy V1 trigger signature (`change`,
+`snapshot`, `message`, `object`) alongside `context`.
+
+______________________________________________________________________
+
+## Cloud Firestore
+
+| V1 Trigger                        | V2 Equivalent         | Destructuring Pattern     |
+| :-------------------------------- | :-------------------- | :------------------------ |
+| `firestore.document().onWrite()`  | `onDocumentWritten()` | `({ change, context })`   |
+| `firestore.document().onCreate()` | `onDocumentCreated()` | `({ snapshot, context })` |
+| `firestore.document().onUpdate()` | `onDocumentUpdated()` | `({ change, context })`   |
+| `firestore.document().onDelete()` | `onDocumentDeleted()` | `({ snapshot, context })` |
+
+______________________________________________________________________
+
+## Cloud Pub/Sub
+
+| V1 Trigger                   | V2 Equivalent          | Destructuring Pattern    |
+| :--------------------------- | :--------------------- | :----------------------- |
+| `pubsub.topic().onPublish()` | `onMessagePublished()` | `({ message, context })` |
+| `pubsub.schedule().onRun()`  | `onSchedule()`         | Access `event` directly  |
+
+> [!NOTE] Scheduled functions moved from the `pubsub` namespace to the
+> `scheduler` namespace in V2.
+
+______________________________________________________________________
+
+## Realtime Database
+
+| V1 Trigger                  | V2 Equivalent      | Destructuring Pattern     |
+| :-------------------------- | :----------------- | :------------------------ |
+| `database.ref().onWrite()`  | `onValueWritten()` | `({ change, context })`   |
+| `database.ref().onCreate()` | `onValueCreated()` | `({ snapshot, context })` |
+| `database.ref().onUpdate()` | `onValueUpdated()` | `({ change, context })`   |
+| `database.ref().onDelete()` | `onValueDeleted()` | `({ snapshot, context })` |
+
+______________________________________________________________________
+
+## Cloud Storage
+
+| V1 Trigger                            | V2 Equivalent               | Destructuring Pattern   |
+| :------------------------------------ | :-------------------------- | :---------------------- |
+| `storage.object().onArchive()`        | `onObjectArchived()`        | `({ object, context })` |
+| `storage.object().onDelete()`         | `onObjectDeleted()`         | `({ object, context })` |
+| `storage.object().onFinalize()`       | `onObjectFinalized()`       | `({ object, context })` |
+| `storage.object().onMetadataUpdate()` | `onObjectMetadataUpdated()` | `({ object, context })` |
+
+______________________________________________________________________
+
+## HTTP / Callables
+
+| V1 Trigger          | V2 Equivalent       | Destructuring Pattern          |
+| :------------------ | :------------------ | :----------------------------- |
+| `https.onRequest()` | `https.onRequest()` | Standard Express `(req, res)`  |
+| `https.onCall()`    | `https.onCall()`    | Destructure `({ data, auth })` |
+
+> [!IMPORTANT] **HTTP Callables do NOT use the Destructuring Shim.** In V2, the
+> handler receives a single `CallableRequest` object (not a `CloudEvent`). You
+> should destructure properties like `data`, `auth`, and `app` directly from it.
+> The traditional `context` object is **unavailable**.
+
+______________________________________________________________________
+
+## Auth (Blocking)
+
+| V1 Trigger                   | V2 Equivalent                   | Destructuring Pattern   |
+| :--------------------------- | :------------------------------ | :---------------------- |
+| `auth.user().beforeSignIn()` | `identity.beforeUserSignedIn()` | Access `event` directly |
+| `auth.user().beforeCreate()` | `identity.beforeUserCreated()`  | Access `event` directly |
+
+> [!NOTE] Auth Blocking triggers moved to the `identity` namespace in V2.
+
+______________________________________________________________________
+
+## Cloud Tasks
+
+| V1 Trigger                       | V2 Equivalent        | Destructuring Pattern   |
+| :------------------------------- | :------------------- | :---------------------- |
+| `tasks.taskQueue().onDispatch()` | `onTaskDispatched()` | Access `event` directly |

package/dist/global-skills/firebase-ai-logic-basics/SKILL.md

@@ -2,6 +2,8 @@
 name: firebase-ai-logic-basics
 description: Official skill for integrating Firebase AI Logic (Gemini API) into web applications. Covers setup, multimodal inference, structured output, and security.
 version: 1.0.1
+metadata:
+  category: AiAndMachineLearning
 ---
 
 # Firebase AI Logic Basics
@@ -16,25 +18,25 @@ of Google's AI integration platform for mobile and web developers.
 
 It supports the two Gemini API providers:
 
-- **Gemini Developer API**: It has a free tier ideal for prototyping, and
-  pay-as-you-go for production
-- **Vertex AI Gemini API**: Ideal for scale with enterprise-grade production
-  readiness, requires Blaze plan
+-   **Gemini Developer API**: It has a free tier ideal for prototyping, and
+    pay-as-you-go for production
+-   **Agent Platform Gemini API** (formerly branded Vertex AI): Ideal for scale
+    with enterprise-grade production readiness, requires Blaze plan
 
-Use the Gemini Developer API as a default, and only Vertex AI Gemini API if the
-application requires it.
+Use the Gemini Developer API as a default, and only Agent Platform Gemini API
+(formerly branded Vertex AI) if the application requires it.
 
 ## Setup & Initialization
 
 ### Prerequisites
 
-- Before starting, ensure you have **Node.js 16+** and npm installed. Install
-  them if they aren’t already available.
-- Identify the platform the user is interested in building on prior to starting:
-  Android, iOS, Flutter or Web.
-- If their platform is unsupported, Direct the user to Firebase Docs to learn
-  how to set up AI Logic for their application (share this link with the user
-  https://firebase.google.com/docs/ai-logic/get-started)
+-   Before starting, ensure you have **Node.js 16+** and npm installed. Install
+    them if they aren’t already available.
+-   Identify the platform the user is interested in building on prior to
+    starting: Android, iOS, Flutter or Web.
+-   If their platform is unsupported, Direct the user to Firebase Docs to learn
+    how to set up AI Logic for their application (share this link with the user
+    https://firebase.google.com/docs/ai-logic/get-started)
 
 ### Installation
 
@@ -95,7 +97,7 @@ faster display of results.
 > [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt)
 > for the currently supported image generation (Nano Banana) model names.
 
-- Requires an upgraded Blaze pay-as-you-go billing plan.
+-   Requires an upgraded Blaze pay-as-you-go billing plan.
 
 ### Search Grounding with the built in googleSearch tool
 
@@ -130,6 +132,36 @@ See
 [App Check with reCAPTCHA Enterprise](https://firebase.google.com/docs/app-check/web/recaptcha-enterprise-provider.md.txt)
 for setup instructions.
 
+#### App Check Debug Tokens for Local Development & CI/CD
+
+Because App Check attestation providers (like Play Integrity or DeviceCheck)
+reject emulators, simulators, or CI environments, you must use **App Check Debug
+Tokens** during development and testing to bypass standard attestation.
+
+##### Local Development (Auto-Generated)
+
+1.  Configure your code's App Check provider to use the debug factory:
+    *   **Web**: Set `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;` before
+        initializing App Check.
+    *   **Android**: Install `DebugAppCheckProviderFactory.getInstance()`.
+    *   **iOS**: Set provider factory to `AppCheckDebugProviderFactory()`.
+2.  Run your app in the emulator/localhost.
+3.  Look at your runtime debugger console / Logcat logs for the generated UUID:
+    *   *Example:* `AppCheck debug token:
+        "123a4567-b89c-12d3-e456-789012345678"`
+4.  Register this token in the Firebase Console under **Security > App Check >
+    Apps > Manage debug tokens**.
+
+##### CI/CD Pipelines (Pre-Provisioned)
+
+1.  Generate and register a new debug token in the Firebase Console under
+    **Security > App Check > Apps > Manage debug tokens**.
+2.  Add this token string as an encrypted secret in your CI system (e.g.
+    `APP_CHECK_DEBUG_TOKEN`).
+3.  Configure your build to pass this secret as an environment variable to the
+    SDK during test execution (e.g. `self.FIREBASE_APPCHECK_DEBUG_TOKEN =
+    process.env.APP_CHECK_DEBUG_TOKEN`).
+
 ### Remote Config
 
 Consider that you do not need to hardcode model names (e.g., a specific model
@@ -145,11 +177,21 @@ without deploying new client code. See
 
 ## Initialization Code References
 
-| Language, Framework, Platform | Gemini API provider                  | Context URL                                     |
-| :---------------------------- | :----------------------------------- | :---------------------------------------------- |
-| Web Modular API               | Gemini Developer API (Developer API) | firebase://docs/ai-logic/get-started            |
-| iOS (Swift)                   | Gemini Developer API                 | [ios_setup.md](references/ios_setup.md)         |
-| Flutter (Dart)                | Gemini Developer API                 | [flutter_setup.md](references/flutter_setup.md) |
+| Language,   | Gemini API | Context URL                                     |
+: Framework,  : provider   :                                                 :
+: Platform    :            :                                                 :
+| :---------- | :--------- | :---------------------------------------------- |
+| Web Modular | Gemini     | firebase://docs/ai-logic/get-started            |
+: API         : Developer  :                                                 :
+:             : API        :                                                 :
+:             : (Developer :                                                 :
+:             : API)       :                                                 :
+| iOS (Swift) | Gemini     | [ios_setup.md](references/ios_setup.md)         |
+:             : Developer  :                                                 :
+:             : API        :                                                 :
+| Flutter     | Gemini     | [flutter_setup.md](references/flutter_setup.md) |
+: (Dart)      : Developer  :                                                 :
+:             : API        :                                                 :
 
 > [!WARNING] **CRITICAL: Use current model names:** Always check the
 > [Firebase AI Logic Models documentation](https://firebase.google.com/docs/ai-logic/models.md.txt)