@mcpher/gas-fakes 2.3.13 → 2.3.15

package/README.md

@@ -1,4 +1,4 @@
-# <img src="./logo.png" alt="gas-fakes logo" width="50" align="top"> Run Native Apps Script code anywhere with gas-fakes
+# <img src="./pngs/logo.png" alt="gas-fakes logo" width="50" align="top"> Run Native Apps Script code anywhere with gas-fakes
 
 ## Google Apps Script, meet Local Development. 
 
@@ -175,18 +175,23 @@ For inspiration on pushing modified files to the IDE, see the togas.sh bash scri
 
 As I mentioned earlier, to take this further, I'm going to need a lot of help to extend the methods and services supported - so if you feel this would be useful to you, and would like to collaborate, please ping me on bruce@mcpher.com and we'll talk.
 
-## <img src="./logo.png" alt="gas-fakes logo" width="50" align="top"> Further Reading
+## <img src="./pngs/logo.png" alt="gas-fakes logo" width="50" align="top"> Further Reading
 
-## Watch the video
+## Watch the gas-fakes intro video
 
-[![Watch the video](introvideo.png)](https://youtu.be/oEjpIrkYpEM)
+[![Watch the intro video](./pngs/introvideo.png)](https://youtu.be/oEjpIrkYpEM)
+
+## Watch the gf_agent video on natural language automation
+
+[![Use natural language with gf_agent](./pngs/gfagent.png)](https://youtu.be/lujByoX71HU)
 
 ## Read more docs
 
 - [gas fakes intro video](https://youtu.be/oEjpIrkYpEM)
 - [getting started](GETTING_STARTED.md) - how to handle authentication for Workspace scopes.
 - [readme](README.md)
-- [Natural Language Automation with Gemini Skills & MCP Server](gemini-skills-mcp.md) - new skills-based agent approach.
+- [Natural Language Automation with Gemini Skills & MCP Server](notes/gemini-skills-mcp.md) - new skills-based agent approach.
+- [Add agent skills to gf_agent](https://ramblings.mcpher.com/add-skills-gf_agent/)
 - [gf_agent documentation](../gf_agent/README.md) - instructions for the Gemini CLI automation agent and MCP server.
 - [gas fakes cli](notes/gas-fakes-cli.md)
 - [github actions using adc](https://github.com/brucemcpherson/gas-fakes-actions-adc)
@@ -239,3 +244,4 @@ As I mentioned earlier, to take this further, I'm going to need a lot of help to
 - [Secure and Streamlined Google Apps Script Development with gas-fakes CLI and Gemini CLI Extension](https://medium.com/google-cloud/secure-and-streamlined-google-apps-script-development-with-gas-fakes-cli-and-gemini-cli-extension-67bbce80e2c8)
 - [Secure and Conversational Google Workspace Automation: Integrating Gemini CLI with a gas-fakes MCP Server](https://medium.com/google-cloud/secure-and-conversational-google-workspace-automation-integrating-gemini-cli-with-a-gas-fakes-mcp-0a5341559865)
 - [A Fake-Sandbox for Google Apps Script: A Feasibility Study on Securely Executing Code Generated by Gemini CL](https://medium.com/google-cloud/a-fake-sandbox-for-google-apps-script-a-feasibility-study-on-securely-executing-code-generated-by-cc985ce5dae3)
+

package/gf_agent/README.md

@@ -0,0 +1,101 @@
+# gf_agent - Google Apps Script Local Automation Agent
+
+`gf_agent` is an interactive agent for Gemini CLI that allows you to automate Google Workspace tasks locally using [gas-fakes](https://github.com/brucemcpherson/gas-fakes).
+
+*For full project details, see the [main gas-fakes README](../README.md).*
+
+## Requirements & Setup
+
+Before using the agent or the MCP tools, you **must** configure your local environment to allow access to your Google Workspace account:
+
+1. **Manifest File**: You need a local `appsscript.json` file in your directory containing the necessary `oauthScopes` you intend to use.
+2. **Initialization**: Run `gas-fakes init` to generate a `.env` file and configure your auth parameters.
+3. **Authentication**: Run `gas-fakes auth` to log in and generate the tokens required to run the scripts.
+
+## Installation & Integration
+
+*Note: You can skip these manual steps if you already chose to install the Gemini skills during the `gas-fakes init` process. The `init` command will automatically detect if you are in a local clone and link the skills appropriately.*
+
+### 1. Install the Skill Agent
+
+**For General Users:**
+You can install the `gf_agent` directly from this repository. To install **only** this skill:
+```bash
+gemini skills install https://github.com/brucemcpherson/gas-fakes.git --path gf_agent
+```
+*Note: This repository contains multiple specialized skills (for development, maintenance, etc.). Omitting the `--path` flag will install all of them.*
+
+**For Contributors & Developers:**
+Do **not** use the `install` command with the remote URL, as it will download a cached copy that is difficult to edit. Because `gf_agent` is a subfolder of the main `gas-fakes` repository, use Git Sparse Checkout to isolate it:
+
+```bash
+mkdir gf_agent_standalone && cd gf_agent_standalone
+git init
+git remote add origin https://github.com/brucemcpherson/gas-fakes.git
+git config core.sparseCheckout true
+echo "gf_agent/*" >> .git/info/sparse-checkout
+git pull origin main
+gemini skills link ./gf_agent
+```
+
+### 2. Configure the MCP Server
+To use Google Workspace services as tools within Gemini CLI, add the MCP server to your settings. 
+
+The easiest way is to use the built-in command (assuming you installed `gas-fakes` globally):
+```bash
+gemini mcp add --scope project gas-fakes-mcp gas-fakes mcp
+```
+
+*(Advanced: Alternatively, you can manually add the configuration to your `.gemini/settings.json` file instead of using the command above. See [documentation.md](documentation.md) for the manual JSON structure).*
+
+### 3. Requirements
+Ensure dependencies are installed in your workspace:
+```bash
+npm install
+```
+
+## Usage
+
+Once the MCP server is configured, you don't need to use any special prefixes or agent names. Simply describe what you want to do in plain English:
+
+- "Create a sheet called 'Latest Drive Files' and add my recently created Drive files to it."
+- "Find latest 5 emails from 'Martin Hawksey' and summarize them in a Google Doc."
+- "Add a meeting with Martin Hawksey to my calendar for tomorrow at 10am. Subject is gas-fakes agent"
+- "Find my airports spreadsheet, and using the sheet with the most data, list to the console the 5 highest airports sorted by elevation high to low, and convert elevation to meters.
+
+The LLM will automatically:
+1. Identify the correct Google Workspace services needed.
+2. Generate the appropriate Apps Script code.
+3. Execute it locally via `gas-fakes`.
+4. Confirm the results to you.
+
+## Antigravity & MCP Integration
+
+`gas-fakes` can also act as an MCP (Model Context Protocol) server for tools like Antigravity. To launch the MCP server:
+
+```bash
+gas-fakes mcp
+```
+
+This allows Antigravity or other MCP-compatible clients to call Google Workspace tools directly through `gas-fakes`.
+
+
+## Why use gf_agent?
+
+- **Fast Iteration**: Test your automation logic without waiting for the Apps Script IDE or deployment.
+- **Security**: Run tasks locally using your own Google credentials (via ADC) without uploading code to a third-party service.
+- **Powerful Integration**: Use Node.js libraries alongside Google Apps Script APIs.
+
+## Contributing to gf_agent
+
+If you'd like to improve the agent by teaching it new tricks, outlining Apps Script API parity warnings, or documenting best practices, we welcome your contributions!
+
+To avoid Git merge conflicts on the large monolithic `SKILL.md` file, the `gf_agent` uses a **modular knowledge base**.
+
+1. Clone or fork this repository (or just the `gf_agent` directory).
+2. Create a new Markdown file inside the `gf_agent/knowledge/` directory (e.g., `06-new-feature.md`).
+3. Write your specific instructions or lessons learned in that file.
+4. **Do NOT** attempt to compile `SKILL.md` yourself.
+5. Commit and submit a Pull Request with your new Markdown file.
+
+Once merged, the repository maintainers will run the automated pipeline to compile your new knowledge into the master `gf_agent/SKILL.md` for all users! See the [Knowledge Base README](knowledge/README.md) or ask the `gf-agent-contributor` skill for more details.

package/gf_agent/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: gf_agent
+description: >
+  Specialized agent for automating Google Workspace tasks locally using gas-fakes.
+  Generates and executes Google Apps Script code on Node.js.
+---
+# Skill: gf_agent
+
+## Overview
+`gf_agent` is a specialized agent for automating Google Workspace tasks using the `gas-fakes` local emulation environment. It can generate and execute Google Apps Script (GAS) code locally on Node.js.
+
+## Capabilities
+- **Automate Workspace**: Create, read, and modify Google Docs, Sheets, Slides, Forms, Drive files, and Calendars.
+- **Local Execution**: Run scripts using `@mcpher/gas-fakes` to avoid needing a live Apps Script environment for every task.
+- **Service Integration**: Seamlessly combine multiple Google services (e.g., fetch data from a Sheet and create a Doc).
+- **Mock/Real Parity**: Write code that works both locally (using fakes) and on the real Google Apps Script platform.
+
+## Instructions
+1. **Understand and Orchestrate**:
+    - Identify required Google Apps Script services (e.g., SpreadsheetApp, DriveApp).
+    - For multi-service or complex tasks, adopt the **Orchestrator Pattern**: Plan the task as a sequence of service-specific sub-tasks.
+2. **Research and Verify (Service Agent Phase)**:
+    - For each service, first verify method existence by reading the local `skills/{service}.md` files in the skill directory.
+    - If detailed method signatures or descriptions are needed, fetch the latest implementation details from the remote `gas-fakes` repository.
+    - **Remote URL**: `https://raw.githubusercontent.com/brucemcpherson/gas-fakes/main/progress/{service}.md` (Note: `{service}` is lowercase, e.g., `spreadsheet.md`).
+    - Use these details to construct precise, parity-compliant code without relying on external search engines unless documentation is missing.
+3. **Generate Script**: Create a Node.js script that:
+    - Imports `@mcpher/gas-fakes`.
+    - Uses standard GAS syntax.
+    - (Optional) Uses `ScriptApp.isFake` for local-only logic like logging or cleanup.
+4. **Execute & Verify**: Use the `mcp_gas-fakes-mcp_workspace_agent` tool to execute the code and report the results to the user.
+
+## Example Workflow
+User: "Summarize the last 5 unread emails and save the summary to a new Google Doc."
+Agent:
+1. **Identify Services**: `GmailApp`, `DocumentApp`.
+2. **Verify Methods**: 
+   - Check `skills/gmail.md` and `skills/document.md`.
+   - (Optional) Fetch `progress/gmail.md` and `progress/document.md` from GitHub for detailed signatures.
+3. **Generate Script**:
+   ```javascript
+   import '@mcpher/gas-fakes';
+   const threads = GmailApp.getInboxThreads(0, 5);
+   let summary = 'Email Summary:\n\n';
+   threads.forEach(t => {
+     const msg = t.getMessages()[0];
+     summary += `From: ${msg.getFrom()}\nSubject: ${msg.getSubject()}\n---\n`;
+   });
+   const doc = DocumentApp.create('Email Summaries');
+   doc.getBody().appendParagraph(summary);
+   console.log('Summary saved to Doc ID:', doc.getId());
+   ```
+4. **Execute**: Call `mcp_gas-fakes-mcp_workspace_agent({ script: '...' })`.
+5. **Report**: Confirm completion and provide the Doc ID.
+
+## Notes
+- Always use ES modules (`import`).
+- Note that the Apps Script Services are all  automatically available- for Example DriveApp, SpreadsheetApp, etc. are all available in the global namespace - no need to import them.
+- the manifest file is used to conteol which scopes are required. dwd is the preferred authentication method but it needs the user to enable it from the domain admain console during the authentication stage.
+- Advanced Service versions of the services are available - and map to their apps script equivalents. These are also available via the global namespace for example Drive, Sheets , etc. 
+- Note that Apps Script is synchronous. gas-fake emulates this so all calls to services will be synchronous
+- Where possible, use the native Apps Script service (for example DriveApp) in preference to the advanced services (Drive, Sheets, etc.)
+
+## Lessons Learned & Best Practices (from Test Patterns)
+
+
+### Execution Context & Artifacts (CRITICAL)
+- **Role Boundary**: You are the `gf_agent` operating on behalf of an end-user to automate Google Workspace tasks. You are NOT a developer writing internal tests for the `gas-fakes` emulator repository.
+- **Transient Execution**: When fulfilling automation requests (e.g., "Create a sheet", "Summarize emails"), you MUST use the provided MCP execution tools (e.g., `run_script` or `mcp_gas-fakes-mcp_workspace_agent`) to execute code dynamically on-the-fly.
+- **No Permanent Artifacts**: DO NOT write script files to disk (e.g., in a `test/` folder) to execute user tasks, and DO NOT use the internal `gas-fakes` testing harness (like `initTests()`). The end-user of `gf_agent` does not have or care about the emulator's testing environment. Provide the plain Apps Script code directly as a string parameter to the MCP tool.
+
+### Efficient Drive Searching (Best Practice)
+- **Prefer `searchFiles()` over manual iteration**: When looking for specific files (e.g., by name, date, or parent), always use `DriveApp.searchFiles(query)` instead of `DriveApp.getFiles()` with manual filtering. Searching happens on the server and is significantly faster.
+- **Date Formatting for Queries**: When searching by date (e.g., `modifiedTime` or `createdTime`), you MUST use the RFC3339 format (e.g., `YYYY-MM-DDThh:mm:ss`). 
+  - **Crucial**: Use `modifiedTime` instead of `modifiedDate` when querying Drive via `gas-fakes`, as it maps to the Drive API v3 field.
+  - *Example*: `DriveApp.searchFiles("modifiedTime >= '2024-04-24T00:00:00'")`.
+
+### Advanced Service Versioning (v3 Preference)
+- **Drive API**: `gas-fakes` follows the **Drive API v3** naming convention. 
+  - Use `Drive.Files.create()` instead of `insert()`.
+  - Use `name` instead of `title` in resource objects.
+  - If a method from a live Apps Script snippet fails, check for its v3 equivalent before assuming it is missing.
+- **Service Discovery**: If unsure about available methods, run a short `workspace_agent` script to log `Object.keys(Service.SubService)` to confirm implemented endpoints.
+
+
+### Common Apps Script Syntax Gotchas (First-Time Accuracy)
+- **File Conversion (Exporting to PDF)**: While live Apps Script can seamlessly convert text files (`text/plain`) to PDF using `file.getAs('application/pdf')`, the underlying Google Drive API **only supports exporting Docs Editor files** (Docs, Sheets, Slides).
+  - **Automated Workaround in gas-fakes**: `gas-fakes` handles this transparently! If you attempt to convert a non-editor file to PDF locally via `.getAs()`, it automatically performs a temporary two-step conversion (copying it to a Google Doc, exporting it, and trashing the temp file). This ensures parity with live Apps Script without manual intervention.
+- **Google Docs Formatting**: You CANNOT apply formatting (bold, italic, etc.) directly to a `Paragraph` or `ListItem`. You MUST use `editAsText()` first.
+  - *Incorrect*: `paragraph.setItalic(true)`
+  - *Correct*: `paragraph.editAsText().setItalic(true)`
+- **Google Docs Element Detachment**: To move or duplicate an element (like an image, paragraph, or table) within a document, you **cannot** just append it if it's already attached to the document tree. You must either detach it (`element.removeFromParent()`) or copy it (`element.copy()`) first, otherwise an "Element must be detached" error is thrown.
+- **Google Docs Headers/Footers**: You can only add one header/footer to a document tab. Calling `doc.addHeader()` twice will throw an error.
+- **Google Sheets Developer Metadata**: You **cannot** add `DeveloperMetadata` to an arbitrary range (e.g., `A1:B2`) or a partial row/column. It **only** works on full sheets, full rows (`9:9`), full columns (`J:J`), or the spreadsheet itself.
+- **Google Sheets Filters**: A sheet can only have one filter at a time. Attempting to call `range.createFilter()` on a sheet that already has a filter will throw an error.
+- **Google Drive Blob Naming**: When creating a file from a Blob (`DriveApp.createFile(blob)`), the Blob **must** have a name. `Utilities.newBlob("content")` does not set a name by default and will throw "Blob object must have non-null name". Always use `Utilities.newBlob("content", "text/plain", "filename.txt")`.
+- **Flush Requirements**: If your script creates a resource and immediately tries to perform a complex search or metadata operation on it, call `SpreadsheetApp.flush()` or `doc.saveAndClose()` to ensure the state is synchronized.
+- **Date Comparison**: When comparing dates from `getLastUpdated()` or `getDateCreated()`, remember they are JavaScript `Date` objects. Use `.getTime()` for reliable numerical comparison.
+
+
+### Authentication & Troubleshooting
+- **Permission Denied/Auth Failures**: Most authentication errors stem from a mismatch between the script's required scopes and the authorized environment.
+  - **Manifest & Scopes**: `gas-fakes` reads `appsscript.json` to discover required scopes. If these scopes weren't authorized during `gas-fakes auth`, the script will fail.
+  - **Advice for User (Auth Methods)**: When a user needs help setting up authentication for `gas-fakes`, advise them based on their specific situation:
+    - **Service Account (Default)**: Recommend this for most automated tasks or server environments. They need a GCP project, a Service Account, and its JSON key file.
+    - **DWD (Domain Wide Delegation)**: Recommend this if the script needs to act on behalf of other users in a Google Workspace domain. Remind the user that the Service Account must be explicitly authorized in the Google Workspace Admin Console (Security > API Controls > Domain-wide Delegation) for the specific scopes being used, and they must provide the `Subject` email address during the `gas-fakes auth` flow.
+    - **Desktop/OAuth (CLI)**: Recommend this for personal scripting or if they cannot use a Service Account. It requires `OAuth Client ID` credentials from GCP (Application type: Desktop) and will prompt them to authenticate via a browser window.
+  - **Initialization**: Ensure the project has been initialized using `gas-fakes init`. The `.env` file must contain the correct `GF_PLATFORM_AUTH` and associated credentials.
+
+### Parity & Platform Logic
+- **`ScriptApp.isFake`**: Use this boolean to detect the `gas-fakes` environment.
+  - **Best Practice**: Guard **only** infrastructure logic (logging, cache checks, special backends) with this flag. 
+  - **Warning**: Do **not** use it to change the core business logic of a script, as this defeats the purpose of parity.
+- **Backend Selection**: `ScriptApp.__platform` can be dynamically switched to target `google`, `ksuite`, or `msgraph`. 
+  - **Self-Correcting**: `gas-fakes` resources (Files, Sheets) "remember" their platform at creation. Subsequent calls on that object will automatically use the correct backend even if `ScriptApp.__platform` has changed globally.
+
+
+### Advanced Service Usage & Interop
+- **Metadata Access**: If a standard service object (e.g., `Spreadsheet`) doesn't expose a specific property, use `Service.__getMetaProps(fields)` or `Service.__getMeta()` to fetch the underlying JSON resource from the Google API.
+- **Batching and Flush**:
+  - **Spreadsheets**: Use `SpreadsheetApp.flush()` to force calculation and commitment of values.
+  - **Documents**: Use `doc.saveAndClose()` followed by `DocumentApp.openById(id)` to synchronize the "Shadow Document" state with the Google servers.
+- **Advanced Drive (v3)**:
+  - **List Files**: `Drive.Files.list({ q: "...", fields: "files(id, name)" })` is the most efficient way to batch fetch file metadata.
+  - **Permissions**: `Drive.Permissions.create({ role, type, emailAddress }, fileId)` is preferred for programmatic sharing.
+- **Iterators**: `gas-fakes` iterators (like `FileIterator`) implement the native Apps Script `hasNext()` and `next()` methods, which differ from standard JavaScript iterators.
+
+### Google Docs & Images
+- **Inline Image Resizing**: Native methods like `setWidth()`/`setHeight()` are **NOT** implemented.
+- **Conversion**: To create a Google Doc from HTML, use `Drive.Files.create()` with the correct v3 parameters:
+  ```javascript
+  const resource = { name: "Doc Name", mimeType: "application/vnd.google-apps.document" };
+  Drive.Files.create(resource, htmlBlob);
+  ```
+- **Resizing Workaround**: The Docs API does not support updating image properties. You must **delete and re-insert** the image with the new dimensions.
+  - **Crucial**: Always sort your delete/insert requests by `startIndex` in **descending order** when performing multiple operations in a single `batchUpdate`. This prevents index shifting from invalidating subsequent operations in the same batch.
+- **Shadow Document & Named Ranges**: `gas-fakes` uses a "Shadow Document" approach. Elements are tracked using Named Range tags to maintain positional integrity during updates.
+- **Table Creation**: `appendTable()` without arguments creates a 1x1 table in `gas-fakes`, whereas live Apps Script creates an empty table stub.
+- **Rate Limiting (429 Errors)**: Because `gas-fakes` translates local calls into real-time API requests, making rapid, successive calls like `appendParagraph()` in a loop will trigger Google's rate limit. 
+  - **Best Practice**: Concatenate strings locally and make a single `appendParagraph()` call, rather than appending multiple short lines separately.
+  - **Real-time Feedback**: If you see retryable 429 errors in the console output during script execution, you MUST inform the user that the process is experiencing rate limiting but that `gas-fakes` is automatically handling retries.
+
+
+### Google Sheets (SpreadsheetApp)
+- **Chart Creation & Ranges**: When using `EmbeddedChartBuilder.addRange()`, the Sheets API requires `ChartSourceRange` domains and series to have a length of 1 for either rows or columns.
+  - **Crucial**: Do **not** pass a multi-column range to `addRange()`. Add domains and series as separate single-column ranges.
+- **Values vs. Display Values**: 
+  - `getValues()` returns unformatted data.
+  - `getDisplayValues()` returns formatted strings.
+  - `setValues()` uses "USER_ENTERED" mode.
+- **Bulk Operations (RangeList)**: Use `sheet.getRangeList(['A1', 'C1', 'E1'])` for multi-range formatting.
+
+### Google Forms (FormApp)
+- **Programmatic Submission**: The public Forms API does **not** support submitting responses. `gas-fakes` uses a "web submission hack" that temporarily makes the form public to scrape tokens and POST the response.
+- **Choice IDs**: The Forms API uses hex string IDs, while Apps Script uses numbers. `gas-fakes` handles this conversion automatically.
+
+### JDBC
+- **MySQL 8+ Authentication**: You must downgrade users to `mysql_native_password` on the server for successful connection.
+- **BigDecimal**: Always wrap `getBigDecimal()` result in `Number()` or `parseFloat()` for cross-platform compatibility.
+
+### Chart Generation Parity (SpreadsheetApp.newChart)
+When implementing Google Sheets Embedded Charts, be aware of the following Live Apps Script vs. REST API oddities:
+- **Enum Strictness**: Live GAS actively rejects string literals for `Charts` Enums (e.g., passing `"SHOW_ALL"` instead of `Charts.ChartHiddenDimensionStrategy.SHOW_ALL` throws `The parameters (String) don't match the method signature`). Ensure your generated test scripts strictly use the Enum objects.
+- **Method Availability**: Live GAS does not support visual formatting methods (`setTitle`, `setBackgroundColor`) on the generic `EmbeddedChartBuilder` returned by `sheet.newChart()`. They are only available *after* casting to a specific builder (e.g., `.asPieChart().setTitle(...)`). 
+- **Hidden Dimensions Crash**: `setHiddenDimensionStrategy` will throw a backend `Unexpected error` if called before assigning a chart type, or if called on an incompatible type (like a Pie chart or Table chart). Only call it on compatible builders (like a Bar or Column chart).
+
+### Environment-Agnostic Test Design
+- When generating scripts or test assertions designed to run interoperably (both locally on Node.js and on Live Apps Script), **never assert against internal private properties** (e.g., properties prefixed with `__`, like `__apiChart`). These properties do not exist on the Live Apps Script Java classes and will cause the script to crash in the cloud environment. Only assert against public, documented getter/setter methods.
+
+
+### JDBC & Cloud SQL Troubleshooting
+
+#### 1. MySQL 8.x/8.4 Authentication Plugin
+**The Problem:** Apps Script's JDBC driver is incompatible with the default `caching_sha2_password` security in MySQL 8.0+.
+**The Solution:** Use the legacy `mysql_native_password` plugin.
+1. **Enable Database Flag:** In Cloud SQL Console, add the flag `mysql_native_password` and set it to `on`.
+2. **Downgrade User:** Run `ALTER USER 'your-user'@'%' IDENTIFIED WITH mysql_native_password BY 'your-password';`.
+
+#### 2. GCP Project Configuration
+**The Problem:** Connection fails even with correct DB credentials because the script isn't authorized to "tunnel" to the instance.
+**The Solution:**
+1. **Enable API:** Ensure the **Cloud SQL Admin API** is enabled in the Google Cloud project.
+2. **IAM Role:** The user running the script (or the service account) must have the **Cloud SQL Client** (`roles/cloudsql.client`) role.
+3. **OAuth Scopes:** The script must include the `https://www.googleapis.com/auth/sqlservice` scope. Add this to your `appsscript.json` manifest if not automatically prompted.
+
+#### 3. Connection Syntax
+**The Problem:** Using IP addresses with `getCloudSqlConnection`.
+**The Solution:** Use the **Instance Connection Name** (`project:region:instance`).
+- **MySQL:** `jdbc:google:mysql://INSTANCE_CONNECTION_NAME/DATABASE_NAME`
+- **PostgreSQL:** `jdbc:google:postgres://INSTANCE_CONNECTION_NAME/DATABASE_NAME`
+- **SQL Server:** `jdbc:google:sqlserver://INSTANCE_CONNECTION_NAME/DATABASE_NAME`
+
+### JDBC & Cloud SQL Authentication Guide
+
+#### 1. "Failed to establish a database connection" (Generic Error)
+This is the most common error. Systematically check:
+- **Cloud SQL Admin API**: MUST be enabled in the Google Cloud Console for the project.
+- **IAM Permissions**: The authenticated user (or service account) must have the **Cloud SQL Client** role (`roles/cloudsql.client`).
+- **OAuth Scopes**: Your `appsscript.json` manifest must include the `"https://www.googleapis.com/auth/sqlservice"` scope.
+- **Instance Connection Name**: Ensure you are using the full name (`project-id:region:instance-id`) and not just the instance ID or IP address when using `getCloudSqlConnection`.
+
+#### 2. "Access denied for user" (Database Level)
+Even if the secure tunnel is established, the database engine may reject the user:
+- **Host Wildcard**: In MySQL/PostgreSQL, users are often restricted by host (e.g., `'user'@'localhost'`). Connections via `getCloudSqlConnection` appear as coming from an internal Google network. Ensure your user is created with a wildcard host or a host that allows Google's internal ranges (e.g., `'user'@'%'`).
+- **Password Complexity**: While `Jdbc.getCloudSqlConnection` handles passwords as separate arguments (avoiding URI encoding issues), double-check for typos or expired passwords.
+
+#### 3. MySQL 8.0+ Authentication Plugin
+MySQL 8.0+ uses `caching_sha2_password` by default, which is incompatible with the Apps Script JDBC driver.
+- **Symptom**: `Handshake failed` or `Access denied` even with correct credentials.
+- **Fix**:
+  1. In the Cloud SQL Console, add the database flag `mysql_native_password` and set it to `on`.
+  2. Run the following SQL to downgrade the user: `ALTER USER 'your-user'@'%' IDENTIFIED WITH mysql_native_password BY 'your-password';`.
+
+#### 4. Connection Methods: Tunneling vs. Public IP
+- **Method A: `Jdbc.getCloudSqlConnection(url, user, password)` (Recommended)**
+  - Works for MySQL and PostgreSQL.
+  - Uses an internal secure tunnel; **no IP whitelisting required**.
+  - URL format: `jdbc:google:mysql://INSTANCE_CONNECTION_NAME/DATABASE_NAME`
+- **Method B: `Jdbc.getConnection(url, user, password)`**
+  - Required for **SQL Server** or non-Google hosted databases.
+  - **IP Whitelisting**: You MUST whitelist Apps Script's public IP ranges in your database firewall/networking settings.
+  - URL format: `jdbc:sqlserver://PUBLIC_IP:1433;databaseName=DB_NAME`
+
+
+### Google Docs API Limitations
+
+- **Horizontal Rules**: The underlying Google Docs API does not support creating, updating, or managing `HorizontalRule` elements. Because `gas-fakes` maps local calls to the REST API, attempting to use methods like `body.appendHorizontalRule()` or `body.insertHorizontalRule()` will crash the script with a `GoogleJsonResponseException` (e.g., `Invalid requests...`).
+  - **Workaround**: If you need to visually separate content in a generated Document, use simple text-based separators like `body.appendParagraph('--------------------------------------------------')` instead.
+
+
+# Orchestrator and Service Agent Pattern
+
+To improve the reliability and accuracy of `gf_agent` when handling complex Google Workspace tasks, the agent should follow an **Orchestrator/Service Agent** architecture. This pattern minimizes "tool space interference" and ensures that the agent always uses the most accurate and up-to-date implementation details for each service.
+
+## The Problem: Tool Space Interference
+When an agent attempts to handle multiple services (e.g., Spreadsheet, Drive, and Gmail) in a single turn, the context can become overwhelmed with conflicting method signatures or outdated knowledge from external search results. This often leads to "hallucinated" methods or incorrect parameter usage.
+
+## The Solution: Modular Delegation
+
+### 1. The Orchestrator Phase
+Upon receiving a user request, the agent acts as an **Orchestrator**. 
+- **Identify Services**: Determine exactly which Apps Script services are required (e.g., `SpreadsheetApp`, `DriveApp`).
+- **Decomposition**: Break the request into service-specific sub-tasks.
+- **Service Verification**: Verify that the required services and classes exist by checking the local `skills/` directory within the `gf_agent` skill.
+
+### 2. The Service Agent Phase (Context Compression)
+For each identified service, the main agent MUST invoke a **sub-agent** (e.g., `generalist`) to perform the deep research.
+- **Why?**: Large documentation files (like `spreadsheet.md`) can bloat the main context window. Sub-agents run in isolated environments and return only a distilled summary.
+- **Process**:
+  1. Main Agent calls `invoke_agent` with the instruction: "Research Class X in Service Y from remote docs. Return ONLY the method signatures for A, B, and C."
+  2. Sub-Agent uses `curl` + `awk` (or `web_fetch`) to find the information.
+  3. Sub-Agent returns a precise report.
+  4. The main context stays lean.
+
+- **Remote Document Retrieval (Sub-Agent Technique)**:
+  - Sub-agents should use `run_shell_command` with `curl` and `awk` for surgical class extraction.
+  - **Branch Routing (CRITICAL)**: 
+    - If the user is operating within the `gas-fakes` repository (developer mode), the sub-agent MUST run `git branch --show-current` to determine the active branch, and use THAT branch name in the URL. This ensures they get work-in-progress signatures.
+    - If the user is operating outside the repository (end-user mode), the sub-agent MUST ALWAYS use the `main` branch.
+  - **Command Template**:
+  - `curl -s https://raw.githubusercontent.com/brucemcpherson/gas-fakes/{BRANCH_NAME}/progress/{Service}.md | awk '/^## Class: \[{ClassName}\]/{flag=1; print; next} /^## Class:/{if(flag) {flag=0; exit}} flag'`
+  - *(Note: `{Service}.md` is case-sensitive. Check `gf_agent/skills/` for the exact casing, e.g., `Spreadsheet.md`)*
+
+### 3. Synthesis and Execution
+Once all required service-specific knowledge is gathered:
+- **Unified Implementation**: Combine the gathered patterns into a single, cohesive Apps Script block.
+- **Execution**: Use the `mcp_gas-fakes-mcp_workspace_agent` to execute the script.
+- **Validation**: If the script fails, the agent returns to the Service Agent phase for the failing service to re-verify the implementation details.
+
+## Benefits
+- **Zero-Search Dependency**: By using the remote `progress` files as the primary source of truth, the agent avoids the risk of using outdated or non-parity GAS snippets found on the web.
+- **Context Efficiency**: Researching one service at a time prevents the "interference" of unrelated documentation.
+- **Parity Guarantee**: The remote documentation is generated directly from the `gas-fakes` source code, ensuring 100% parity with the local environment.
+
+## Delegation Anti-Patterns (CRITICAL)
+- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (e.g., `mcp_gas-fakes-mcp_workspace_agent`). 
+- **Subagent Context Loss**: Subagents do **not** inherit the `gf_agent` knowledge base, parity rules, or active skills. If you tell a subagent to "execute these 5 tasks," it will generate standard Google Apps Script code that ignores `gas-fakes` specific workarounds (like avoiding `HorizontalRule` or `modifiedDate`), leading to widespread failures.
+- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase). The main agent writes and runs the code.
+
+## Safe Parallelism (Performance)
+While delegating *orchestration* is dangerous, performing tasks in parallel is highly encouraged for efficiency. The orchestrator should achieve this in two ways:
+1. **Tool Call Parallelism**: The Main Agent generates multiple, parity-compliant scripts and issues them as independent, simultaneous calls to `mcp_gas-fakes-mcp_workspace_agent` within a single turn.
+2. **Execution-Level Async**: Since `gas-fakes` runs on Node.js, the Main Agent can generate a single script that uses `Promise.all()` to execute multiple non-dependent operations (like `UrlFetchApp` calls or creating separate files) simultaneously.
+3. **Sequence when Dependent**: Only use `wait_for_previous: true` or sequential turns when a task depends on the side-effect of a previous one (e.g., reading a sheet that was just created).
+
+
+# Sandbox and Security Controls
+
+`gf_agent` can operate in a **Sandbox Mode** to ensure that automated tasks are restricted to specific files, recipients, or usage quotas. This is critical for preventing accidental modification of sensitive data or exceeding API limits.
+
+## Core Concepts
+
+### 1. Enabling the Sandbox
+The sandbox is controlled via `ScriptApp.__behavior`. Enabling it locks down the environment.
+```javascript
+ScriptApp.__behavior.sandboxMode = true;
+ScriptApp.__behavior.strictSandbox = true; // Only allow files created in this session
+```
+
+### 2. ID Whitelisting (Files & Folders)
+In `strictSandbox` mode, all external files are blocked by default. Use whitelisting to grant granular access.
+- **Pattern**: `addIdWhitelist(item)`
+- **Permissions**: `.setRead(true)`, `.setWrite(true)`, `.setTrash(true)`
+```javascript
+const behavior = ScriptApp.__behavior;
+const item = behavior.newIdWhitelistItem('FILE_ID')
+  .setRead(true)
+  .setWrite(false) // Read-only
+  .setTrash(false);
+behavior.addIdWhitelist(item);
+```
+
+### 3. Gmail Security
+The Gmail service has specialized sandbox settings under `sandboxService.GmailApp`.
+- **Email Whitelist**: Restricts `sendEmail` to specific addresses.
+- **Label Whitelist**: Restricts which labels can be read, applied, or deleted.
+- **Usage Limits**: Sets quotas for `read`, `write`, `trash`, and `send` operations.
+```javascript
+const gmail = ScriptApp.__behavior.sandboxService.GmailApp;
+gmail.emailWhitelist = ['allowed@example.com'];
+gmail.usageLimit = { send: 5, read: 10 }; // Granular limits
+// OR
+gmail.usageLimit = 50; // Total operations limit
+```
+
+### 4. Service & Method Restrictions
+You can disable entire services or restrict scripts to a subset of allowed methods.
+```javascript
+// Disable a service entirely
+ScriptApp.__behavior.sandboxService.SlidesApp.enabled = false;
+
+// Whitelist specific methods for a service
+ScriptApp.__behavior.sandboxService.DriveApp.setMethodWhitelist(['getFileById', 'getBlob']);
+```
+
+### 5. Automated Cleanup
+The sandbox tracks every resource created during a session. When `behavior.trash()` is called, it automatically deletes these resources unless `cleanup` is disabled.
+```javascript
+ScriptApp.__behavior.cleanup = true; // Default: true
+// Set per-service
+ScriptApp.__behavior.sandboxService.GmailApp.cleanup = false;
+```
+
+## Best Practices for `gf_agent`
+- **Session Isolation**: When a user provides a list of files or emails, always initialize the sandbox with those specific whitelists at the top of the script.
+- **Explicit Whitelisting**: Use `behavior.addIdWhitelist` for file access. DO NOT assume `sandboxService.SpreadsheetApp` has an `addFileWhitelist` method (it is handled globally by the behavior ID whitelist).
+- **Safe Execution**: In the Orchestrator Phase, identify if the task requires external access and include the necessary sandbox boilerplate in the generated script.
+
+
+### Chart Builder Method Limitations (API Parity)
+
+When generating code that builds Embedded Charts in Google Sheets (`SpreadsheetApp.newChart()`), you must adhere to the following restrictions, as `gas-fakes` maps directly to the Google Sheets REST API v4 which has limitations compared to Live Apps Script:
+
+1. **Method Fragmentation (Range Settings)**: 
+   - You MUST NOT use `setXAxisRange()` or `setYAxisRange()` unless you are specifically building a `ScatterChart`. In Live Apps Script, these methods are exclusive to `EmbeddedScatterChartBuilder` and will throw a `TypeError` on other chart types.
+   - For all other chart types (Column, Bar, Line, Area), you MUST use the generic `setRange(min, max)` method.
+
+2. **Unimplemented Formatting Methods**: 
+   - The REST API v4 lacks direct properties for many granular text-styling and sub-scale formatting options. 
+   - You MUST NOT use the following methods as they will throw a `notYetImplemented` error in `gas-fakes`: `useLogScale()`, `setXAxisLogScale()`, `setYAxisLogScale()`, `reverseCategories()`, `reverseDirection()`, `setPointStyle()`, `enablePaging()`, `enableSorting()`, or any method ending in `*TextStyle()` (e.g., `setTitleTextStyle()`).
+   - Stick to core configurations: `setColors()`, `setXAxisTitle()`, `setYAxisTitle()`, `setRange()`, `setStacked()`, `setBackgroundColor()`, `setLegendPosition()`, and `set3D()`.
+
+3. **Pie Chart Custom Colors**: 
+   - The REST API v4 does not support setting custom slice colors for Pie Charts. Calling `setColors()` on a Pie Chart builder will be silently ignored. Do not attempt to style Pie Chart slices.
+
+### Gmail Modifiers and Eventual Consistency
+
+When writing scripts that modify Gmail objects (e.g., `GmailMessage.markRead()`, `GmailMessage.star()`, `GmailThread.markImportant()`), be aware of a significant difference between `gas-fakes` and Live Apps Script regarding synchronization.
+
+- **Live Apps Script (Eventual Consistency)**: Despite documentation claiming these methods are synchronous and "force a refresh", the backend operations are eventually consistent. If you check the state immediately after modifying it (e.g., `message.markRead(); console.log(message.isUnread());`), it will likely return the old state.
+- **Portable Code Pattern**: If you are writing tests or robust code that must run reliably in Live Apps Script as well as `gas-fakes`, you must introduce an artificial delay and manually refresh the object state:
+  ```javascript
+  message.markRead();
+  if (!ScriptApp.isFake) Utilities.sleep(1000); // Wait for Live GAS backend
+  message.refresh(); // Manually force a re-fetch of the state
+  console.log(message.isUnread()); // Now safe to assert
+  ```
+- **gas-fakes Execution**: When executing transient scripts locally via `gas-fakes` that don't need immediate assertions, this pattern is not strictly necessary as `gas-fakes` handles the REST API synchronization reliably, but it is best practice for cross-platform parity.
+
+# gf_agent Knowledge Base
+
+This directory contains modular markdown files representing the "Lessons Learned & Best Practices" for the `gf_agent` skill.
+
+## Contributing
+
+To prevent Git merge conflicts on the monolithic `gf_agent/SKILL.md` file, collaborators should **never edit `gf_agent/SKILL.md` directly**. 
+
+Instead, to add new knowledge or instructions to the agent:
+1. Create a new markdown file in this directory (e.g., `06-new-feature.md`).
+2. Prefix it with a number to control the insertion order.
+3. Write your instructions, tips, or parity warnings.
+4. Commit ONLY your new markdown file and submit a Pull Request.
+
+**Do not attempt to compile the SKILL.md file yourself.**
+When your Pull Request is merged into the core `gas-fakes` repository, the maintainer will run the overarching `npm run docs` pipeline. The `builder.js` script will automatically read all files in this directory, sort them, and cleanly generate the final `gf_agent/SKILL.md` artifact for all users.
+

package/gf_agent/documentation.md

@@ -0,0 +1,105 @@
+# gf_agent Documentation
+
+This document provides patterns and examples for using `gf_agent` and `gas-fakes` to automate Google Workspace tasks.
+
+## Integration Guides
+
+### Gemini CLI & MCP Setup
+To integrate `gf_agent` and its Workspace tools into Gemini CLI:
+
+1. **Link the Skill**:
+   ```bash
+   gemini skills link /Users/brucemcpherson/Documents/repos/gas-fakes/gf_agent
+   ```
+2. **Add MCP Tools**:
+   Run this to register the service-specific tools (Spreadsheet, Doc, Drive, etc.):
+   ```bash
+   gemini mcp add --scope project gas-fakes-mcp node ./gas-fakes.js mcp
+   ```
+3. **Verify**: Run `gemini mcp list` to see the registered `gas-fakes-mcp` tools.
+4. **Use it**:
+   - **As an Agent**: `@gf_agent create a sheet...`
+   - **As Tools**: You don't need to specify the tool name. The LLM automatically infers whether to use `spreadsheet_service`, `drive_service`, or the cross-service `workspace_agent`. Just say: *"Read my latest Drive document and email it to john@example.com."*
+
+### Generic MCP Setup (Antigravity, Claude, etc.)
+`gas-fakes` includes a built-in MCP server that can be used by any MCP-compatible client.
+
+## Core Patterns
+
+### Initialization
+Every script must import `@mcpher/gas-fakes` to enable the local emulation environment.
+```javascript
+import '@mcpher/gas-fakes';
+```
+
+### Google Sheets (SpreadsheetApp)
+#### Create and modify a sheet
+```javascript
+const ss = SpreadsheetApp.create('My New Sheet');
+const sheet = ss.getActiveSheet();
+sheet.getRange('A1').setValue('Item');
+sheet.getRange('B1').setValue('Count');
+sheet.getRange('A2:B2').setValues([['Apples', 10]]);
+```
+
+#### Read data from a sheet
+```javascript
+const ss = SpreadsheetApp.openById('SPREADSHEET_ID');
+const data = ss.getDataRange().getValues();
+console.log(data);
+```
+
+### Google Docs (DocumentApp)
+#### Create and append text
+```javascript
+const doc = DocumentApp.create('My Doc');
+const body = doc.getBody();
+body.appendParagraph('Hello World');
+body.appendListItem('First Item');
+body.appendTable([['Header 1', 'Header 2'], ['Val 1', 'Val 2']]);
+```
+
+### Google Drive (DriveApp)
+#### List files in a folder
+```javascript
+const folder = DriveApp.getFolderById('FOLDER_ID');
+const files = folder.getFiles();
+while (files.hasNext()) {
+  const file = files.next();
+  console.log(file.getName(), file.getId());
+}
+```
+
+#### Create a folder
+```javascript
+const newFolder = DriveApp.createFolder('Project Assets');
+```
+
+### Gmail (GmailApp)
+#### Send an email
+```javascript
+GmailApp.sendEmail('recipient@example.com', 'Subject', 'Body content');
+```
+
+## Advanced Usage
+
+### Using the Sandbox
+By default, `gas-fakes` operates in a sandbox. You can check if you are in fake mode and configure behavior:
+```javascript
+if (ScriptApp.isFake) {
+  const behavior = ScriptApp.__behavior;
+  behavior.sandboxMode = true; // only see files created in this session
+}
+```
+
+### Cleanup
+If you create many test files, you can trash them at the end of the session:
+```javascript
+if (ScriptApp.isFake) {
+  ScriptApp.__behavior.trash();
+}
+```
+
+## Troubleshooting
+- **Method not found**: Check the [Index](index.md) to see if the method is implemented.
+- **Permission denied**: Ensure you are using the correct IDs or that the sandbox is configured to allow access to those IDs.