[DRAFT ONLY] Create agent skills for ABIU and Local Builds

skills/firebase-app-hosting-basics/SKILL.md

@@ -47,12 +47,30 @@ This is the recommended flow for most users.
 3. If the app needs safe access to sensitive keys, use `npx -y firebase-tools@latest apphosting:secrets` commands to set and grant access to secrets.
 4. Run `npx -y firebase-tools@latest deploy` when you are ready to deploy.
 
+### Deploy via Local Builds (Experimental)
+
+If you want faster deployments by bypassing Cloud Build queues, you can compile your full-stack web application locally.
+1. Set up the experiments and configure `"localBuild": true` in your `firebase.json` file.
+2. Run `npx -y firebase-tools@latest deploy --only apphosting` to compile and deploy the pre-built assets.
+
+> [!CAUTION]
+> **SECURITY WARNING FOR CODING AGENTS (AI ASSISTANTS):**
+> - **DO NOT** bypass confirmation using `--allow-local-build-secrets` unless explicitly requested by the developer.
+> - **PAUSE AND WARN** the developer of the severe risk that raw secret values will be downloaded locally and may get permanently compiled into public client-side bundles or cached artifacts.
+> - Review the strict operating system, framework, and security limitations in the [Local Builds Reference](references/local_builds.md).
+
 ### Automated deployment via GitHub (CI/CD)
 
 Alternatively, set up a backend connected to a GitHub repository for automated deployments "git push" deployments.
 This is only recommended for more advanced users, and is not required to use App Hosting.
 See [CLI Commands](references/cli_commands.md) for more information on how to set this up using CLI commands.
 
+## Runtimes & Automatic Base Image Updates (ABIU)
+
+App Hosting supports versioned Node.js runtimes with Automatic Base Image Updates (ABIU) to apply security patches without redeploys.
+- **CRITICAL**: AI Assistants **MUST** inspect the project's `package.json` and check the `engines.node` field before recommending a runtime version or creating a backend. Mismatched runtimes trigger build-time errors.
+- For a complete guide on setup, CLI flags, and lifecycle management, see [Runtimes & ABIU](references/runtimes_and_abiu.md).
+
 ## Emulation
 
 See [Emulation](references/emulation.md) for more information on how to test your app locally using the Firebase Local Emulator Suite.

skills/firebase-app-hosting-basics/references/local_builds.md

@@ -0,0 +1,92 @@
+# App Hosting Local Builds (Experimental)
+
+App Hosting Local Builds is an experimental feature that compiles your full-stack web application (e.g. Next.js) on your local development machine instead of using Google Cloud Build in the cloud. Once compiled, the Firebase CLI packages the pre-built standalone assets and uploads them directly to Cloud Run.
+
+This feature is highly useful for faster deployments, bypassing cloud build queue times, and debugging build outputs locally.
+
+> [!WARNING]
+> This is an early preview of prototype code and you are likely to encounter bugs. Do NOT use this with production backends or sensitive data. Only use test backends and non-sensitive test data as you evaluate this feature.
+
+---
+
+## Mandatory Rules for Coding Agents
+
+> [!CAUTION]
+> **CRITICAL SECURITY INSTRUCTION FOR CODING AGENTS (AI ASSISTANTS):**
+> 1. **DO NOT** run local builds with the `--allow-local-build-secrets` flag unless the developer has explicitly instructed you to bypass confirmations for build secrets.
+> 2. **PAUSE AND WARN** the user if you detect any `BUILD`-available secrets in `apphosting.yaml`. You must explain that:
+>    - Local builds will download the raw, unencrypted secret values from Google Cloud Secret Manager to your local machine.
+>    - These raw secret values can easily be permanently baked into your client-side JavaScript bundles (e.g. due to Next.js bundler behavior) or left behind in local build artifacts/temporary files.
+> 3. **GET EXPLICIT APPROVAL** from the user before proceeding with a local build when secrets are configured.
+
+---
+
+## Setup and Configuration
+
+### 1. Enable Experiments
+Enable the required experimental CLI preview flags on your local machine:
+```bash
+npx -y firebase-tools@latest experiments:enable abiu
+npx -y firebase-tools@latest experiments:enable apphostinglocalbuilds
+```
+
+> [!NOTE]
+> The experiment `universalMaker` is no longer a separate experiment name in the Firebase CLI. All binary management and building capabilities are fully handled under the `apphostinglocalbuilds` experiment.
+
+### 2. Configure `firebase.json`
+To instruct the Firebase CLI to perform a local build during deploy, set `"localBuild": true` in the `apphosting` block of your `firebase.json`:
+
+```json
+{
+  "apphosting": [
+    {
+      "backendId": "my-local-build-backend",
+      "localBuild": true,
+      "rootDir": "/",
+      "ignore": [
+        "node_modules",
+        ".git",
+        "firebase-debug.log",
+        "firebase-debug.*.log",
+        "functions"
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Technical Details (How It Works Under the Hood)
+
+When you execute `npx -y firebase-tools@latest deploy --only apphosting`, the local build flow performs the following steps:
+
+1. **Isolated Scratch Workspace**: The CLI creates a temporary scratch folder named `.local_build_<backendId>` in your project root and copies all project files into it. It applies your `firebase.json` ignore patterns and respects `.gitignore` to ensure a clean build context matching what would have been sent to Cloud Build.
+2. **Secret Injection**: If your `apphosting.yaml` environment contains secrets marked for `BUILD` availability:
+   - In interactive mode, the CLI will prompt you with a warning before downloading.
+   - In non-interactive mode (e.g. CI scripts), the deployment will abort with an error unless the `--allow-local-build-secrets` flag is provided.
+   - The CLI programmatically fetches the raw values from GCP Secret Manager and injects them into the local build process's `process.env`.
+3. **Universal Maker Execution**: The CLI downloads the architecture-aware **Universal Maker** build engine binary (caching it at `~/.cache/firebase/universal-maker/`), verifies its size and SHA256 checksum, and executes it in the scratch folder to compile the application.
+4. **Output Extraction**: The CLI parses the generated `build_output.json` and `.apphosting/bundle.yaml` to extract the application's start-up `runCommand` and stand-alone output files (e.g., `.next/standalone`).
+5. **Tarball Compacting & GCS Upload**: The standalone output folder and configurations are compressed into an optimized `.tar.gz` tarball (ignoring unneeded source or `node_modules`), uploaded to GCS, and the `.local_build_<backendId>` directory is safely deleted.
+6. **Rollout Deployment**: The App Hosting API is invoked with a `locallyBuilt` source payload containing the storage URL, start-up `runCommand`, and discovered environment variables.
+
+---
+
+## All Limitations & Warnings
+
+Before adopting local builds, you must be aware of the following strict limitations:
+
+### 1. Host Platform Restrictions
+The pre-compiled Universal Maker build binary only supports a subset of operating systems and architectures:
+- **macOS**: Only macOS Apple Silicon (`darwin_arm64`) is supported. macOS Intel (`darwin_x64`) is not supported.
+- **Linux**: Only Linux x86-64 (`linux_x64`) is supported. Linux ARM (`linux_arm64`) is not supported.
+- **Windows**: Windows (`win32`) is not supported. Windows developers must deploy from source or run the CLI inside a WSL (Windows Subsystem for Linux) environment.
+
+### 2. Security & Secret Exposure Caveats
+If your build depends on secrets marked for `BUILD` availability, the CLI fetches the raw, unencrypted values from Cloud Secret Manager and sets them as environment variables in the build context.
+- **General Build-Time Risk**: Developers must be extremely cautious when using build-available secrets. Ensure your application code and build scripts do not accidentally expose or embed these sensitive values into client-side bundles, compiled files, or public assets. This risk is universal and is equally critical whether you compile locally or remotely on Google Cloud Build.
+
+### 3. Local Directory Collisions & Artifact Leftovers
+The local build pipeline creates intermediate workspace directories (such as `.local_build_<backendId>`) during the compilation process.
+- **Interrupted Cleanup**: While the CLI is designed to automatically delete these intermediate folders upon a successful build, **if the build process is interrupted, force-quit, or crashes mid-execution, these artifacts may be left on your system**. You will need to manually delete these leftover directories to secure any cached environment variables and to prevent subsequent `firebase deploy` commands from blocking due to directory collisions.

skills/firebase-app-hosting-basics/references/runtimes_and_abiu.md

@@ -0,0 +1,41 @@
+# App Hosting Runtimes & Automatic Base Image Updates (ABIU)
+
+Firebase App Hosting allows you to choose a specific runtime environment (e.g., versioned Node.js) for your backend. When you choose a versioned runtime, **Automatic Base Image Updates (ABIU)** automatically applies security patches to your underlying OS/runtime container without requiring you to rebuild or redeploy.
+
+---
+
+## Mandatory Rules for Coding Agents
+
+> [!IMPORTANT]
+> **CRITICAL RUNTIME COMPATIBILITY INSTRUCTION FOR CODING AGENTS (AI ASSISTANTS):**
+> 1. **Inspect package.json first**: Before recommending a runtime version or running backend creation commands, you **MUST** read the user's `package.json` file and inspect the `engines.node` field (e.g., if `"engines": { "node": ">=22.0.0" }` is specified, you must select `nodejs22` or `nodejs24`).
+> 2. **Prevent mismatch failures**: Creating a backend with a runtime version that is incompatible with the `engines` field will trigger a build failure during the Cloud Build phase.
+> 3. **Warn on default runtime**: If the default unversioned `nodejs` runtime is used, warn the developer that ABIU is completely disabled (leaving their container without automated security updates) and recommend migrating to a versioned runtime (e.g. `nodejs22`).
+
+---
+
+## Setup and Configuration
+
+### 1. Enable runtime Selection
+Ensure the `abiu` experiment is enabled on the local CLI:
+```bash
+npx -y firebase-tools@latest experiments:enable abiu
+```
+
+### 2. Specifying runtime During Backend Creation
+When creating a new backend programmatically or in non-interactive environments, specify the target versioned runtime using the `--runtime` flag:
+```bash
+npx -y firebase-tools@latest apphosting:backends:create --runtime nodejs22 --backend my-backend-name --primary-region us-central1
+```
+
+---
+
+## Runtime Lifecycles & Support
+
+Runtimes progress through the following lifecycle phases (mirroring Cloud Run's support):
+
+| Lifecycle State | Description | Agent Actions |
+| :--- | :--- | :--- |
+| **Supported** | Fully supported. ABIU security patches are active. | Recommend these versions to users. |
+| **Deprecated** | Approaching end of support. Existing apps continue running, but warnings appear in the Console. | Warn the user to migrate to a newer version as soon as possible. |
+| **Decommissioned** | Completely unsupported. New builds or backends using this version will fail with errors. Existing containers may stop working or be deleted. | **NEVER** allow creation of new backends on decommissioned versions. Assist the user in upgrading. |