@mcpher/gas-fakes 2.3.15 → 2.3.17

package/gf_agent/SKILL.md

@@ -25,7 +25,6 @@ description: >
     - **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.
@@ -39,7 +38,6 @@ Agent:
    - (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 => {
@@ -67,6 +65,7 @@ Agent:
 ### 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 Import Required**: Do NOT include `import '@mcpher/gas-fakes';` at the top of your scripts when using the MCP execution tools. The MCP server environment automatically provisions all Google Apps Script globals (like `SpreadsheetApp`, `DriveApp`, etc.) into the execution context for you.
 - **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)
@@ -84,8 +83,9 @@ Agent:
 
 
 ### 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.
+- **File Conversion (Exporting to PDF)**: 
+  - **`DriveApp.File.getAs()` Workaround**: 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). `gas-fakes` handles this transparently by automatically performing 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.
+  - **`Spreadsheet.getAs()` Limitation**: The `getAs()` method is **NOT** implemented directly on `Spreadsheet`, `Document`, or `Presentation` objects in `gas-fakes`. If you try to call `ss.getAs('application/pdf')`, the script will crash. **Crucial Rule**: You MUST fetch the file via DriveApp first to convert it: `DriveApp.getFileById(ss.getId()).getAs('application/pdf')`.
 - **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)`
@@ -126,14 +126,36 @@ Agent:
 - **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.
+- **Inline Image Resizing (DocumentApp)**: Native methods like `setWidth()` and `setHeight()` on `InlineImage` objects are **NOT** implemented in `gas-fakes`. If you call these, the script will crash with a "not yet implemented" error.
 - **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.
+- **Resizing Workaround (Advanced Docs Service)**: Because the Docs API does not support updating image properties directly, you must use the Advanced Docs Service (`Docs.Documents.batchUpdate`) to **delete and re-insert** the image with the new dimensions. 
+  - To do this, fetch the document via `Docs.Documents.get()`, extract the `contentUri` from the existing inline image, and construct `deleteObject` and `insertInlineImage` requests.
+  - **Crucial**: Always sort your delete/insert operations by `startIndex` in **descending order** so you don't corrupt the document's indices during a batch update.
+  - **Example Code Pattern**:
+    ```javascript
+    const docData = Docs.Documents.get(docId);
+    const requests = [];
+    // ... logic to find images in docData.body.content, saving objectId, contentUri, startIndex, and dimensions ...
+    // ... sort found images by startIndex DESCENDING ...
+    images.forEach(img => {
+      requests.push({ deleteObject: { objectId: img.objectId } });
+      requests.push({ 
+        insertInlineImage: { 
+          uri: img.contentUri, 
+          location: { index: img.startIndex }, 
+          objectSize: { 
+            width: { magnitude: img.width * 0.25, unit: 'PT' }, 
+            height: { magnitude: img.height * 0.25, unit: 'PT' } 
+          } 
+        } 
+      });
+    });
+    if (requests.length > 0) Docs.Documents.batchUpdate({ requests }, docId);
+    ```
 - **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. 
@@ -149,6 +171,7 @@ Agent:
   - `getDisplayValues()` returns formatted strings.
   - `setValues()` uses "USER_ENTERED" mode.
 - **Bulk Operations (RangeList)**: Use `sheet.getRangeList(['A1', 'C1', 'E1'])` for multi-range formatting.
+- **Exporting to PDF (`getAs`)**: The `Spreadsheet.getAs()` method is **NOT** implemented in `gas-fakes`. If you need to convert a Spreadsheet (or a Document/Presentation) to a PDF, you MUST use the `DriveApp` service workaround: `DriveApp.getFileById(spreadsheet.getId()).getAs('application/pdf')`.
 
 ### 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.
@@ -273,12 +296,13 @@ Once all required service-specific knowledge is gathered:
 - **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.
+- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (`mcp_gas-fakes-mcp_workspace_agent`). 
+- **Unauthorized Tool Call Error**: Sub-agents (like `generalist`) DO NOT have access to MCP tools. If you use `invoke_agent` to delegate a task that requires executing code, the sub-agent will crash with: `Error: Unauthorized tool call: 'mcp_gas-fakes-mcp_workspace_agent' is not available to this 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, leading to widespread failures.
+- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase) via standard shell commands like `curl`. 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:
+If the user asks you to run multiple tasks in parallel, DO NOT use `invoke_agent`. You must handle them directly in the main session. The orchestrator should achieve parallelism 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).
@@ -344,6 +368,7 @@ 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).
+- **Cross-Platform Portability**: The `ScriptApp.__behavior` object is a `gas-fakes` exclusive feature. If the generated script is intended to be copied and run in Live Apps Script later, you MUST wrap all sandbox-related boilerplate in an `if (ScriptApp.isFake)` block to prevent `TypeError` crashes in the cloud.
 - **Safe Execution**: In the Orchestrator Phase, identify if the task requires external access and include the necessary sandbox boilerplate in the generated script.
 
 
@@ -377,6 +402,45 @@ When writing scripts that modify Gmail objects (e.g., `GmailMessage.markRead()`,
   ```
 - **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.
 
+### Researching Advanced Services (Google API Discovery)
+
+Unlike the standard Apps Script Services (`SpreadsheetApp`, `DriveApp`), the signatures and payloads for **Advanced Services** (`Docs`, `Sheets`, `Drive`, etc.) are not fully documented in the `progress/` directory of the `gas-fakes` repository. Advanced Services are 1:1 mappings of the underlying Google REST APIs.
+
+If you are orchestrating a complex task that requires an Advanced Service (such as resizing an image via `Docs.Documents.batchUpdate` or applying granular formatting via `Sheets.Spreadsheets.batchUpdate`) and you do not know the exact JSON payload structure, you MUST research it using the Google API Discovery documents.
+
+**How to Research Advanced Services:**
+Do not guess the payload structure. Instead, use the `run_shell_command` tool to `curl` and `grep` the official Discovery Document for the specific API version.
+
+**Discovery Document URLs:**
+- **Docs API v1**: `https://docs.googleapis.com/$discovery/rest?version=v1`
+- **Sheets API v4**: `https://sheets.googleapis.com/$discovery/rest?version=v4`
+- **Drive API v3**: `https://drive.googleapis.com/$discovery/rest?version=v3`
+- **Slides API v1**: `https://slides.googleapis.com/$discovery/rest?version=v1`
+- **Gmail API v1**: `https://gmail.googleapis.com/$discovery/rest?version=v1`
+
+**Example Research Command:**
+If you need to know how to structure an `insertInlineImage` request for the Docs API, you would run:
+```bash
+curl -s "https://docs.googleapis.com/$discovery/rest?version=v1" | grep -A 30 '"InsertInlineImageRequest":'
+```
+
+By fetching the exact schema from the discovery document, you ensure your `batchUpdate` arrays and payload objects are 100% accurate before generating the execution script.
+
+### Utilities Service Constraints (API Parity)
+
+When generating code that uses the `Utilities` service, you must adhere to the following restrictions to ensure parity with Live Apps Script:
+
+1. **`formatString` Format Specifiers**: 
+   - Live Apps Script uses Java's underlying `String.format` implementation. Therefore, it **does not** support Node.js-specific format specifiers like `%j` for JSON.
+   - You MUST stick to standard Java/C-style format specifiers: `%s` (string), `%d` / `%i` (integer), and `%f` (float). 
+   - *Incorrect*: `Utilities.formatString("Data: %j", obj)`
+   - *Correct*: `Utilities.formatString("Data: %s", JSON.stringify(obj))`
+
+2. **`parseDate` Error Handling**:
+   - If `Utilities.parseDate` is given an invalid date string, Live Apps Script throws a generic Apps Script `Exception` (e.g., `{"name":"Exception"}`) rather than a standard JavaScript `Error` object. 
+   - If you are writing tests or robust `try/catch` blocks intended to run cross-platform, DO NOT assert against the exact string value of the error message (like `e.message.includes("failed")`). Simply check that an exception was thrown.
+
+
 # gf_agent Knowledge Base
 
 This directory contains modular markdown files representing the "Lessons Learned & Best Practices" for the `gf_agent` skill.

package/gf_agent/index.md

@@ -2,6 +2,8 @@
 
 This index lists all Google Apps Script services and classes supported by `gf_agent` via `gas-fakes`.
 
+- [Gmail](skills/gmail.md)
+- [Spreadsheet](skills/spreadsheet.md)
 - [base](skills/base.md)
 - [cache](skills/cache.md)
 - [calendar](skills/calendar.md)
@@ -9,13 +11,11 @@ This index lists all Google Apps Script services and classes supported by `gf_ag
 - [document](skills/document.md)
 - [drive](skills/drive.md)
 - [forms](skills/forms.md)
-- [gmail](skills/gmail.md)
 - [jdbc](skills/jdbc.md)
 - [lock](skills/lock.md)
 - [properties](skills/properties.md)
 - [script](skills/script.md)
 - [slides](skills/slides.md)
-- [spreadsheet](skills/spreadsheet.md)
 - [urlfetch](skills/urlfetch.md)
 - [utilities](skills/utilities.md)
 - [xml](skills/xml.md)

package/gf_agent/knowledge/00-execution-context.md

@@ -1,4 +1,5 @@
 ### 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 Import Required**: Do NOT include `import '@mcpher/gas-fakes';` at the top of your scripts when using the MCP execution tools. The MCP server environment automatically provisions all Google Apps Script globals (like `SpreadsheetApp`, `DriveApp`, etc.) into the execution context for you.
 - **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.

package/gf_agent/knowledge/02-syntax.md

@@ -1,6 +1,7 @@
 ### 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.
+- **File Conversion (Exporting to PDF)**: 
+  - **`DriveApp.File.getAs()` Workaround**: 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). `gas-fakes` handles this transparently by automatically performing 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.
+  - **`Spreadsheet.getAs()` Limitation**: The `getAs()` method is **NOT** implemented directly on `Spreadsheet`, `Document`, or `Presentation` objects in `gas-fakes`. If you try to call `ss.getAs('application/pdf')`, the script will crash. **Crucial Rule**: You MUST fetch the file via DriveApp first to convert it: `DriveApp.getFileById(ss.getId()).getAs('application/pdf')`.
 - **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)`

package/gf_agent/knowledge/04-advanced.md

@@ -9,14 +9,36 @@
 - **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.
+- **Inline Image Resizing (DocumentApp)**: Native methods like `setWidth()` and `setHeight()` on `InlineImage` objects are **NOT** implemented in `gas-fakes`. If you call these, the script will crash with a "not yet implemented" error.
 - **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.
+- **Resizing Workaround (Advanced Docs Service)**: Because the Docs API does not support updating image properties directly, you must use the Advanced Docs Service (`Docs.Documents.batchUpdate`) to **delete and re-insert** the image with the new dimensions. 
+  - To do this, fetch the document via `Docs.Documents.get()`, extract the `contentUri` from the existing inline image, and construct `deleteObject` and `insertInlineImage` requests.
+  - **Crucial**: Always sort your delete/insert operations by `startIndex` in **descending order** so you don't corrupt the document's indices during a batch update.
+  - **Example Code Pattern**:
+    ```javascript
+    const docData = Docs.Documents.get(docId);
+    const requests = [];
+    // ... logic to find images in docData.body.content, saving objectId, contentUri, startIndex, and dimensions ...
+    // ... sort found images by startIndex DESCENDING ...
+    images.forEach(img => {
+      requests.push({ deleteObject: { objectId: img.objectId } });
+      requests.push({ 
+        insertInlineImage: { 
+          uri: img.contentUri, 
+          location: { index: img.startIndex }, 
+          objectSize: { 
+            width: { magnitude: img.width * 0.25, unit: 'PT' }, 
+            height: { magnitude: img.height * 0.25, unit: 'PT' } 
+          } 
+        } 
+      });
+    });
+    if (requests.length > 0) Docs.Documents.batchUpdate({ requests }, docId);
+    ```
 - **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. 

package/gf_agent/knowledge/05-sheets-forms.md

@@ -6,6 +6,7 @@
   - `getDisplayValues()` returns formatted strings.
   - `setValues()` uses "USER_ENTERED" mode.
 - **Bulk Operations (RangeList)**: Use `sheet.getRangeList(['A1', 'C1', 'E1'])` for multi-range formatting.
+- **Exporting to PDF (`getAs`)**: The `Spreadsheet.getAs()` method is **NOT** implemented in `gas-fakes`. If you need to convert a Spreadsheet (or a Document/Presentation) to a PDF, you MUST use the `DriveApp` service workaround: `DriveApp.getFileById(spreadsheet.getId()).getAs('application/pdf')`.
 
 ### 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.

package/gf_agent/knowledge/09-orchestrator-pattern.md

@@ -43,12 +43,13 @@ Once all required service-specific knowledge is gathered:
 - **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.
+- **NEVER Delegate Execution**: The main orchestrator agent MUST retain control of script generation and the execution tool (`mcp_gas-fakes-mcp_workspace_agent`). 
+- **Unauthorized Tool Call Error**: Sub-agents (like `generalist`) DO NOT have access to MCP tools. If you use `invoke_agent` to delegate a task that requires executing code, the sub-agent will crash with: `Error: Unauthorized tool call: 'mcp_gas-fakes-mcp_workspace_agent' is not available to this 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, leading to widespread failures.
+- **Strict Role Boundary**: Subagents are strictly for **isolated documentation retrieval** (the Service Agent Phase) via standard shell commands like `curl`. 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:
+If the user asks you to run multiple tasks in parallel, DO NOT use `invoke_agent`. You must handle them directly in the main session. The orchestrator should achieve parallelism 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).

package/gf_agent/knowledge/10-sandbox-security.md

@@ -58,4 +58,5 @@ 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).
+- **Cross-Platform Portability**: The `ScriptApp.__behavior` object is a `gas-fakes` exclusive feature. If the generated script is intended to be copied and run in Live Apps Script later, you MUST wrap all sandbox-related boilerplate in an `if (ScriptApp.isFake)` block to prevent `TypeError` crashes in the cloud.
 - **Safe Execution**: In the Orchestrator Phase, identify if the task requires external access and include the necessary sandbox boilerplate in the generated script.

package/gf_agent/knowledge/13-advanced-services-discovery.md

@@ -0,0 +1,23 @@
+### Researching Advanced Services (Google API Discovery)
+
+Unlike the standard Apps Script Services (`SpreadsheetApp`, `DriveApp`), the signatures and payloads for **Advanced Services** (`Docs`, `Sheets`, `Drive`, etc.) are not fully documented in the `progress/` directory of the `gas-fakes` repository. Advanced Services are 1:1 mappings of the underlying Google REST APIs.
+
+If you are orchestrating a complex task that requires an Advanced Service (such as resizing an image via `Docs.Documents.batchUpdate` or applying granular formatting via `Sheets.Spreadsheets.batchUpdate`) and you do not know the exact JSON payload structure, you MUST research it using the Google API Discovery documents.
+
+**How to Research Advanced Services:**
+Do not guess the payload structure. Instead, use the `run_shell_command` tool to `curl` and `grep` the official Discovery Document for the specific API version.
+
+**Discovery Document URLs:**
+- **Docs API v1**: `https://docs.googleapis.com/$discovery/rest?version=v1`
+- **Sheets API v4**: `https://sheets.googleapis.com/$discovery/rest?version=v4`
+- **Drive API v3**: `https://drive.googleapis.com/$discovery/rest?version=v3`
+- **Slides API v1**: `https://slides.googleapis.com/$discovery/rest?version=v1`
+- **Gmail API v1**: `https://gmail.googleapis.com/$discovery/rest?version=v1`
+
+**Example Research Command:**
+If you need to know how to structure an `insertInlineImage` request for the Docs API, you would run:
+```bash
+curl -s "https://docs.googleapis.com/$discovery/rest?version=v1" | grep -A 30 '"InsertInlineImageRequest":'
+```
+
+By fetching the exact schema from the discovery document, you ensure your `batchUpdate` arrays and payload objects are 100% accurate before generating the execution script.

package/gf_agent/knowledge/14-utilities-parity.md

@@ -0,0 +1,13 @@
+### Utilities Service Constraints (API Parity)
+
+When generating code that uses the `Utilities` service, you must adhere to the following restrictions to ensure parity with Live Apps Script:
+
+1. **`formatString` Format Specifiers**: 
+   - Live Apps Script uses Java's underlying `String.format` implementation. Therefore, it **does not** support Node.js-specific format specifiers like `%j` for JSON.
+   - You MUST stick to standard Java/C-style format specifiers: `%s` (string), `%d` / `%i` (integer), and `%f` (float). 
+   - *Incorrect*: `Utilities.formatString("Data: %j", obj)`
+   - *Correct*: `Utilities.formatString("Data: %s", JSON.stringify(obj))`
+
+2. **`parseDate` Error Handling**:
+   - If `Utilities.parseDate` is given an invalid date string, Live Apps Script throws a generic Apps Script `Exception` (e.g., `{"name":"Exception"}`) rather than a standard JavaScript `Error` object. 
+   - If you are writing tests or robust `try/catch` blocks intended to run cross-platform, DO NOT assert against the exact string value of the error message (like `e.message.includes("failed")`). Simply check that an exception was thrown.

package/gf_agent/scripts/SKILL.template.md

@@ -25,7 +25,6 @@ description: >
     - **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.
@@ -39,7 +38,6 @@ Agent:
    - (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 => {