chore: add workflow for updating the public api surface

Author: lahirumaramba

.agents/workflows/api-surface-updates.md

@@ -0,0 +1,21 @@
+---
+description: How to make changes to the public API surface
+---
+
+# Updating the Public API Surface
+
+This codebase (Firebase Admin Node.js SDK) uses `api-extractor` to automatically track and document the public-facing API surface. Any time you modify exported interfaces, signatures, JSDoc comments, or anything else belonging to the public surface of the SDK, you **must** update the API reports.
+
+## Steps
+
+1. Make your code changes (e.g., adding a property to an interface, modifying JSDoc, adding a new exported class).
+2. Write appropriate unit and integration tests.
+3. Run the complete test suite.
+4. Run the API Extractor report generator command from the root of the project:
+   ```bash
+   npm run api-extractor:local
+   ```
+5. Running `api-extractor:local` first runs the `build` script (`npm run build`), which takes a moment. It then updates any outdated `.md` files located in the `etc/` folder (such as `etc/firebase-admin.app-check.api.md`).
+6. You will see modified `.md` report files inside `etc/` in `git status`. Stage these changes alongside your code changes when doing `git commit`.
+
+**Remember**: Failure to run this script will result in the CI rejecting the PR because the generated API surface reports commit will be out-of-sync with the codebase!