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

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

@@ -39,7 +39,7 @@ to upgrade their plan.
 This is the recommended flow for most users.
 
 1. Configure `firebase.json` with an `apphosting` block.
-   
+
    ```json
    {
      "apphosting": {
@@ -55,14 +55,37 @@ This is the recommended flow for most users.
      }
    }
    ```
+
 1. Create or edit `apphosting.yaml`- see
    [Configuration](references/configuration.md) for more information on how to
    do so.
+
 1. 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.
+
 1. 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. Enable the `apphostinglocalbuilds` experiment and configure
+   `"localBuild": true` in your `firebase.json` file.
+1. 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
@@ -71,6 +94,17 @@ 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

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

@@ -0,0 +1,150 @@
+# 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.
+> 1. **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.
+> 1. **GET EXPLICIT APPROVAL** from the user before proceeding with a local
+>    build when secrets are configured.
+
+______________________________________________________________________
+
+## Setup and Configuration
+
+### 1. Enable Experiment
+
+Enable the experimental CLI preview flag on your local machine:
+
+```bash
+npx -y firebase-tools@latest experiments:enable apphostinglocalbuilds
+```
+
+### 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.
+1. **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`.
+1. **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.
+1. **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`).
+1. **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.
+1. **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
+  either deploy from source (using Cloud Build) or run the CLI inside a WSL
+  (Windows Subsystem for Linux) environment to perform local builds.
+
+### 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,51 @@
+# 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`).
+> 1. **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.
+> 1. **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`).
+
+______________________________________________________________________
+
+## 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. |