Add dotguides

.guides/config.json

@@ -0,0 +1,9 @@
+{
+  "description": "A set of guides for Cloud Functions for Firebase.",
+  "mcpServers": {
+    "firebase": {
+      "command": "firebase",
+      "args": ["mcp:server"]
+    }
+  }
+}

.guides/examples/index.md

@@ -0,0 +1,5 @@
+# Firebase Functions Samples
+
+For useful and minimal samples for various function triggers, please refer to the official Firebase Functions quickstarts repository on GitHub:
+
+[https://github.com/firebase/functions-samples/tree/main/Node/quickstarts](https://github.com/firebase/functions-samples/tree/main/Node/quickstarts)

.guides/setup.md

@@ -0,0 +1,74 @@
+# Firebase Functions Setup Guide
+
+This guide provides a step-by-step process for setting up a new Firebase Functions project, tailored for a coding agent.
+
+### **Step 1: Initialize Firebase Project**
+
+If you haven't already, initialize your Firebase project. The agent should have the `firebase-tools` CLI installed.
+
+```bash
+# One-time setup for a new project
+firebase login
+firebase init functions
+```
+During initialization, select `TypeScript`.
+
+### **Step 2: Install Dependencies**
+
+Navigate to the `functions` directory and install the necessary NPM packages.
+
+```bash
+cd functions
+npm install
+```
+
+### **Step 3: Create a v2 HTTP Function**
+
+Replace the contents of `src/index.ts` with the following code to create a simple, modern v2 HTTP endpoint.
+
+```typescript
+import {onRequest} from "firebase-functions/v2/https";
+import * as logger from "firebase-functions/logger";
+import {defineString} from "firebase-functions/params";
+
+// Define a configuration parameter for a greeting
+const greeting = defineString("GREETING", {default: "Hello"});
+
+export const helloWorld = onRequest((request, response) => {
+  logger.info("Request received!", {structuredData: true});
+  response.send(`${greeting.value()} from Firebase!`);
+});
+```
+
+**Key points for the agent:**
+*   Always import from `firebase-functions/v2/*` for new functions.
+*   Use `logger` for structured logging.
+*   Use `defineString`, `defineInt`, `defineSecret` for environment configuration instead of `functions.config()`.
+
+### **Step 4: Build TypeScript**
+
+Compile your TypeScript code to JavaScript.
+
+```bash
+npm run build
+```
+
+### **Step 5: Local Development and Testing**
+
+Use the Firebase Emulators to test your function locally before deploying.
+
+```bash
+# Start the functions emulator
+firebase emulators:start --only functions
+```
+The agent can then interact with the function at the local URL provided by the emulator.
+
+### **Step 6: Deploy to Firebase**
+
+Once testing is complete, deploy the function to your Firebase project.
+
+```bash
+# Deploy only the functions
+firebase deploy --only functions
+```
+The agent will be prompted to set any parameters defined with `defineString` or other `define` functions that do not have a default value.

.guides/upgrade.md

@@ -0,0 +1,154 @@
+# Upgrading Firebase Functions to 2nd Gen
+
+This guide summarizes the process of migrating Cloud Functions from 1st to 2nd generation. You can migrate functions incrementally, running both generations side-by-side.
+
+## 1. Update Dependencies
+
+Update your `firebase-functions` and `firebase-admin` SDKs, and ensure you are using a recent version of the Firebase CLI.
+
+## 2. Modify Imports
+
+Update your import statements to use the `v2` subpackage.
+
+**Before (1st Gen):**
+```typescript
+import * as functions from "firebase-functions";
+```
+
+**After (2nd Gen):**
+```typescript
+import * as functions from "firebase-functions/v2";
+```
+
+## 3. Update Trigger Definitions
+
+The SDK is now more modular. Update your trigger definitions accordingly.
+
+### HTTP Triggers
+
+**Before (1st Gen):**
+```typescript
+export const webhook = functions.https.onRequest((request, response) => {
+  // ...
+});
+```
+
+**After (2nd Gen):**
+```typescript
+import {onRequest} from "firebase-functions/v2/https";
+
+export const webhook = onRequest((request, response) => {
+  // ...
+});
+```
+
+### Callable Triggers
+
+**Before (1st Gen):**
+```typescript
+export const getprofile = functions.https.onCall((data, context) => {
+  // ...
+});
+```
+
+**After (2nd Gen):**
+```typescript
+import {onCall} from "firebase-functions/v2/https";
+
+export const getprofile = onCall((request) => {
+  // ...
+});
+```
+
+### Background Triggers (Pub/Sub)
+
+**Before (1st Gen):**
+```typescript
+export consthellopubsub = functions.pubsub.topic("topic-name").onPublish((message) => {
+  // ...
+});
+```
+
+**After (2nd Gen):**
+```typescript
+import {onMessagePublished} from "firebase-functions/v2/pubsub";
+
+export consthellopubsub = onMessagePublished("topic-name", (event) => {
+  // ...
+});
+```
+
+## 4. Use Parameterized Configuration
+
+Migrate from `functions.config()` to the new `params` module for environment configuration. This provides strong typing and validation.
+
+**Before (`.runtimeconfig.json`):**
+```json
+{
+  "someservice": {
+    "key": "somesecret"
+  }
+}
+```
+**And in code (1st Gen):**
+```typescript
+const SKEY = functions.config().someservice.key;
+```
+
+**After (2nd Gen):**
+Define params in your code and set their values during deployment.
+
+**In `index.ts`:**
+```typescript
+import {defineString} from "firebase-functions/params";
+
+const SOMESERVICE_KEY = defineString("SOMESERVICE_KEY");
+```
+Use `SOMESERVICE_KEY.value()` to access the value. For secrets like API keys, use `defineSecret`.
+
+**In `index.ts`:**
+```typescript
+import {defineSecret} from "firebase-functions/params";
+
+const SOMESERVICE_KEY = defineSecret("SOMESERVICE_KEY");
+```
+You will be prompted to set the value on deployment, which is stored securely in Cloud Secret Manager.
+
+## 5. Update Runtime Options
+
+Runtime options are now set directly within the function definition.
+
+**Before (1st Gen):**
+```typescript
+export const func = functions
+  .runWith({
+    // Keep 5 instances warm
+    minInstances: 5,
+  })
+  .https.onRequest((request, response) => {
+    // ...
+  });
+```
+
+**After (2nd Gen):**
+```typescript
+import {onRequest} from "firebase-functions/v2/https";
+
+export const func = onRequest(
+  {
+    // Keep 5 instances warm
+    minInstances: 5,
+  },
+  (request, response) => {
+    // ...
+  }
+);
+```
+
+## 6. Traffic Migration
+
+To migrate traffic safely:
+1.  Rename your new 2nd gen function with a different name.
+2.  Deploy it alongside the old 1st gen function.
+3.  Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function).
+4.  Once you are confident, you can delete the 1st gen function.

.guides/usage.md

@@ -0,0 +1,90 @@
+This guide covers Firebase Functions SDK v6.0.0+.
+
+**Key Guidelines**
+*   Always use v2 functions for new development.
+*   Use v1 functions *only* for Analytics, basic Auth, and Test Lab triggers.
+*   For SDK versions before 6.0.0, add `/v2` to import paths (e.g., `firebase-functions/v2/https`).
+
+**Configuration: Use Secret Params for API Keys**
+For sensitive information like API keys (e.g., for LLMs, payment providers, etc.), **always** use `defineSecret`. This stores the value securely in Cloud Secret Manager.
+
+```typescript
+import {onRequest} from 'firebase-functions/v2/https';
+import {logger} from 'firebase-functions/logger';
+import {defineString, defineSecret} from 'firebase-functions/params';
+
+// Securely define an LLM API key
+const LLM_API_KEY = defineSecret('LLM_API_KEY');
+
+// Example function that uses the secret
+export const callLlm = onRequest({ secrets: [LLM_API_KEY] }, (req, res) => {
+  const apiKey = LLM_API_KEY.value();
+
+  // Use the apiKey to make a call to the LLM service
+  logger.info('Calling LLM with API key.');
+
+  res.send('LLM API call initiated.');
+});
+```
+When you deploy a function with `secrets`, the CLI will prompt you to enter the secret's value.
+
+**Initializing the Firebase Admin SDK**
+To interact with Firebase services like Firestore, Auth, or RTDB from within your functions, you need to initialize the Firebase Admin SDK.
+
+1.  **Install the SDK:**
+    ```bash
+    npm i firebase-admin
+    ```
+
+2.  **Initialize in your code:**
+    ```typescript
+    import * as admin from 'firebase-admin';
+
+    admin.initializeApp();
+    ```
+    This should be done once at the top level of your `index.ts` file.
+
+**Common Imports**
+```typescript
+// HTTPS, Firestore, RTDB, Scheduled, Storage, Pub/Sub, Auth, Logging, Config
+import {onRequest} from 'firebase-functions/https';
+import {onDocumentUpdated} from 'firebase-functions/firestore';
+import {onValueWritten} from 'firebase-functions/database';
+import {onSchedule} from 'firebase-functions/scheduler';
+import {onObjectFinalized} from 'firebase-functions/storage';
+import {onMessagePublished} from 'firebase-functions/pubsub';
+import {beforeUserSignedIn} from 'firebase-functions/identity';
+import {logger} from 'firebase-functions';
+import {defineString, defineSecret} from 'firebase-functions/params';
+```
+
+**v1 Functions (Legacy Triggers)**
+Use the `firebase-functions/v1` import for Analytics and basic Auth triggers.
+```typescript
+import * as functionsV1 from 'firebase-functions/v1';
+
+// v1 Analytics trigger
+export const onPurchase = functionsV1.analytics.event('purchase').onLog((event) => {
+  logger.info('Purchase event', { value: event.params?.value });
+});
+
+// v1 Auth trigger
+export const onUserCreate = functionsV1.auth.user().onCreate((user) => {
+  logger.info('User created', { uid: user.uid });
+});
+```
+
+**Development Commands**
+```bash
+# Install dependencies
+npm install
+
+# Compile TypeScript
+npm run build
+
+# Run emulators for local development
+firebase emulators:start --only functions
+
+# Deploy functions
+firebase deploy --only functions
+```