address review comments

Author: jhuleatt

.guides/config.json

@@ -1,9 +1,9 @@
 {
-  "description": "A set of guides for Cloud Functions for Firebase.",
+  "description": "Use this library to build serverless functions for event triggers and HTTP using Firebase and Cloud Run Functions",
   "mcpServers": {
     "firebase": {
-      "command": "firebase",
-      "args": ["mcp:server"]
+      "command": "npx",
+      "args": ["-y", "firebase-tools@latest", "experimental:mcp"]
     }
   }
 }

.guides/examples/index.md

@@ -1,69 +1,53 @@
-# Firebase Functions Setup Guide
+# Cloud Functions for Firebase 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**
+## 1. Create a 2nd-gen HTTP function
 
-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.
+Replace the contents of `src/index.ts` (or `index.js`) with the following code to create a simple, modern v2 HTTP endpoint.
 
 ```typescript
-import {onRequest} from "firebase-functions/v2/https";
+import {onRequest} from "firebase-functions/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!`);
-});
+export const helloWorld = onRequest(
+  { maxInstances: 1 },
+  async (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.
+*   Always import from `firebase-functions/*` for new functions.
 *   Use `logger` for structured logging.
 *   Use `defineString`, `defineInt`, `defineSecret` for environment configuration instead of `functions.config()`.
 
-### **Step 4: Build TypeScript**
+## 2. Build TypeScript
 
 Compile your TypeScript code to JavaScript.
 
 ```bash
 npm run build
 ```
 
-### **Step 5: Local Development and Testing**
+## 3. Local Development and Testing
 
 Use the Firebase Emulators to test your function locally before deploying.
 
+Tell the user to run the following command in a separate terminal window to start the emulators:
 ```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.
+The user can then interact with the function at the local URL provided by the emulator.
 
-### **Step 6: Deploy to Firebase**
+## 4. Deploy to Firebase
 
 Once testing is complete, deploy the function to your Firebase project.
 

.guides/setup.md

@@ -1,47 +1,48 @@
-# Upgrading Firebase Functions to 2nd Gen
+# Upgrading a Firebase Function 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.
+This guide provides a step-by-step process for migrating a single Cloud Function from 1st to 2nd generation. Migrate functions incrementally, running both generations side-by-side.
 
-## 1. Update Dependencies
+## 1. Identify a v1 function to upgrade
 
-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.
+Let's say you have a 1st gen HTTP function like this:
 
 **Before (1st Gen):**
 ```typescript
 import * as functions from "firebase-functions";
-```
 
-**After (2nd Gen):**
-```typescript
-import * as functions from "firebase-functions/v2";
+export const webhook = functions.https.onRequest((request, response) => {
+  // ...
+});
 ```
 
-## 3. Update Trigger Definitions
+Now, let's upgrade it to 2nd gen.
 
-The SDK is now more modular. Update your trigger definitions accordingly.
+## 2. Update Dependencies
 
-### HTTP Triggers
+Ensure your `firebase-functions` and `firebase-admin` SDKs are up-to-date, and you are using a recent version of the Firebase CLI.
 
-**Before (1st Gen):**
+## 3. Modify Imports
+
+Update your import statements to use the top-level modules.
+
+**After (2nd Gen):**
 ```typescript
-export const webhook = functions.https.onRequest((request, response) => {
-  // ...
-});
+import {onRequest} from "firebase-functions/https";
 ```
 
+## 4. Update Trigger Definition
+
+The SDK is now more modular. Update your trigger definition accordingly.
+
 **After (2nd Gen):**
 ```typescript
-import {onRequest} from "firebase-functions/v2/https";
-
 export const webhook = onRequest((request, response) => {
   // ...
 });
 ```
 
+Here are other examples of trigger changes:
+
 ### Callable Triggers
 
 **Before (1st Gen):**
@@ -53,7 +54,7 @@ export const getprofile = functions.https.onCall((data, context) => {
 
 **After (2nd Gen):**
 ```typescript
-import {onCall} from "firebase-functions/v2/https";
+import {onCall} from "firebase-functions/https";
 
 export const getprofile = onCall((request) => {
   // ...
@@ -64,23 +65,23 @@ export const getprofile = onCall((request) => {
 
 **Before (1st Gen):**
 ```typescript
-export consthellopubsub = functions.pubsub.topic("topic-name").onPublish((message) => {
+export const hellopubsub = functions.pubsub.topic("topic-name").onPublish((message) => {
   // ...
 });
 ```
 
 **After (2nd Gen):**
 ```typescript
-import {onMessagePublished} from "firebase-functions/v2/pubsub";
+import {onMessagePublished} from "firebase-functions/pubsub";
 
-export consthellopubsub = onMessagePublished("topic-name", (event) => {
+export const hellopubsub = onMessagePublished("topic-name", (event) => {
   // ...
 });
 ```
 
-## 4. Use Parameterized Configuration
+## 5. Use Parameterized Configuration
 
-Migrate from `functions.config()` to the new `params` module for environment configuration. This provides strong typing and validation.
+Migrate from `functions.config()` to the new `params` module for environment configuration.
 
 **Before (`.runtimeconfig.json`):**
 ```json
@@ -114,7 +115,7 @@ 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
+## 6. Update Runtime Options
 
 Runtime options are now set directly within the function definition.
 
@@ -132,7 +133,7 @@ export const func = functions
 
 **After (2nd Gen):**
 ```typescript
-import {onRequest} from "firebase-functions/v2/https";
+import {onRequest} from "firebase-functions/https";
 
 export const func = onRequest(
   {
@@ -145,10 +146,12 @@ export const func = onRequest(
 );
 ```
 
-## 6. Traffic Migration
+## 7. 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.
+2.  Comment out any existing `minInstances` or `maxInstances` config and instead set `maxInstances` to `1` while testing.
+3.  Deploy it alongside the old 1st gen function.
+4.  Gradually introduce traffic to the new function (e.g., via client-side changes or by calling it from the 1st gen function).
+5.  Add back the original `minInstances` and `maxInstances` settings to the 2nd gen function.
+6.  Once you are confident, you can delete the 1st gen function.

.guides/upgrade.md

@@ -1,35 +1,38 @@
-This guide covers Firebase Functions SDK v6.0.0+.
+## Key Guidelines
 
-**Key Guidelines**
-*   Always use v2 functions for new development.
+*   Always use 2nd-gen 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`).
+*   Use `firebase-functions` SDK version 6.0.0 and above
+*   Use top-level imports (e.g., `firebase-functions/https`). These are 2nd gen by default.
+
+## Configuration: Use Secret Params for API Keys
 
-**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 {onRequest} from 'firebase-functions/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) => {
+export const callLlm = onRequest({ secrets: [LLM_API_KEY] }, async (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.');
+
+  // insert code here to call LLM...
 
   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.
+## Use 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. Call `initializeApp` without any arguments so that Application Default Credentials are used.
 
 1.  **Install the SDK:**
     ```bash
@@ -44,7 +47,7 @@ To interact with Firebase services like Firestore, Auth, or RTDB from within you
     ```
     This should be done once at the top level of your `index.ts` file.
 
-**Common Imports**
+## Common Imports
 ```typescript
 // HTTPS, Firestore, RTDB, Scheduled, Storage, Pub/Sub, Auth, Logging, Config
 import {onRequest} from 'firebase-functions/https';
@@ -54,27 +57,27 @@ 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 {logger, onInit} 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.
+## 1st-gen Functions (Legacy Triggers)**
+Use the `firebase-functions/v1` import for Analytics and basic Auth triggers. These aren't supported in 2nd gen.
 ```typescript
 import * as functionsV1 from 'firebase-functions/v1';
 
 // v1 Analytics trigger
-export const onPurchase = functionsV1.analytics.event('purchase').onLog((event) => {
+export const onPurchase = functionsV1.analytics.event('purchase').onLog(async (event) => {
   logger.info('Purchase event', { value: event.params?.value });
 });
 
 // v1 Auth trigger
-export const onUserCreate = functionsV1.auth.user().onCreate((user) => {
+export const onUserCreate = functionsV1.auth.user().onCreate(async (user) => {
   logger.info('User created', { uid: user.uid });
 });
 ```
 
-**Development Commands**
+## Development Commands
 ```bash
 # Install dependencies
 npm install
@@ -83,7 +86,10 @@ npm install
 npm run build
 
 # Run emulators for local development
+# Tell the user to run the following command to start the emulators:
+```bash
 firebase emulators:start --only functions
+```
 
 # Deploy functions
 firebase deploy --only functions

.guides/usage.md

@@ -10,12 +10,12 @@ Learn more about the Firebase SDK for Cloud Functions in the [Firebase documenta
 
 Here are some resources to get help:
 
-- Start with the quickstart: https://firebase.google.com/docs/functions/write-firebase-functions
-- Go through the guide: https://firebase.google.com/docs/functions/
-- Read the full API reference: https://firebase.google.com/docs/reference/functions/
-- Browse some examples: https://github.com/firebase/functions-samples
+- [Start with the quickstart](https://firebase.google.com/docs/functions/write-firebase-functions)
+- [Go through the guide](https://firebase.google.com/docs/functions/)
+- [Read the full API reference](https://firebase.google.com/docs/reference/functions/)
+- [Browse some examples](https://github.com/firebase/functions-samples)
 
-If the official documentation doesn't help, try asking through our official support channels: https://firebase.google.com/support/
+If the official documentation doesn't help, try asking through our [official support channels](https://firebase.google.com/support/)
 
 _Please avoid double posting across multiple channels!_