google-apps-script

Original source / Raw SKILL.md

---
name: google-apps-script
description: "Build Google Apps Script automation for Sheets and Workspace apps. Produces scripts with custom menus, triggers, dialogs, email automation, PDF export, and external API integration."
---

# Google Apps Script

Build automation scripts for Google Sheets and Workspace apps. Scripts run server-side on Google's infrastructure with a generous free tier.

## What You Produce

- Apps Script code pasted into Extensions > Apps Script
- Custom menus, dialogs, sidebars
- Automated triggers (on edit, time-driven, form submit)
- Email notifications, PDF exports, API integrations

## Workflow

### Step 1: Understand the Automation

Ask what the user wants automated. Common scenarios:
- Custom menu with actions (report generation, data processing)
- Auto-triggered behaviour (on edit, on form submit, scheduled)
- Sidebar app for data entry
- Email notifications from sheet data
- PDF export and distribution

### Step 2: Generate the Script

Follow the structure template below. Every script needs a header comment, configuration constants at top, and `onOpen()` for menu setup.

### Step 3: Provide Installation Instructions

All scripts install the same way:
1. Open the Google Sheet
2. **Extensions > Apps Script**
3. Delete any existing code in the editor
4. Paste the script
5. Click **Save**
6. Close the Apps Script tab
7. **Reload the spreadsheet** (onOpen runs on page load)

### Step 4: First-Time Authorisation

Each user gets a Google OAuth consent screen on first run. For unverified scripts (most internal scripts), users must click:

**Advanced > Go to [Project Name] (unsafe) > Allow**

This is a one-time step per user. Warn users about this in your output.

---

## Script Structure Template

Every script should follow this pattern:

```javascript
/**
 * [Project Name] - [Brief Description]
 *
 * [What it does, key features]
 *
 * INSTALL: Extensions > Apps Script > paste this > Save > Reload sheet
 */

// --- CONFIGURATION ---
const SOME_SETTING = 'value';

// --- MENU SETUP ---
function onOpen() {
  const ui = SpreadsheetApp.getUi();
  ui.createMenu('My Menu')
    .addItem('Do Something', 'myFunction')
    .addSeparator()
    .addSubMenu(ui.createMenu('More Options')
      .addItem('Option A', 'optionA'))
    .addToUi();
}

// --- FUNCTIONS ---
function myFunction() {
  // Implementation
}
```

---

## Critical Rules

### Public vs Private Functions

Functions ending with `_` (underscore) are **private** and CANNOT be called from client-side HTML via `google.script.run`. This is a silent failure — the call simply doesn't work with no error.

```javascript
// WRONG - dialog can't call this, fails silently
function doWork_() { return 'done'; }

// RIGHT - dialog can call this
function doWork() { return 'done'; }
```

**Also applies to**: Menu item function references must be public function names as strings.

### Batch Operations (Critical for Performance)

Read/write data in bulk, never cell-by-cell. The difference is 70x.

```javascript
// SLOW (70 seconds on 100x100) - reads one cell at a time
for (let i = 1; i <= 100; i++) {
  const val = sheet.getRange(i, 1).getValue();
}

// FAST (1 second) - reads all at once
const allData = sheet.getRange(1, 1, 100, 1).getValues();
for (const row of allData) {
  const val = row[0];
}
```

Always use `getRange().getValues()` / `setValues()` for bulk reads/writes.

### V8 Runtime

V8 is the **only** runtime (Rhino was removed January 2026). Supports modern JavaScript: `const`, `let`, arrow functions, template literals, destructuring, classes, async/generators.

**NOT available** (use Apps Script alternatives):

| Missing API | Apps Script Alternative |
|-------------|------------------------|
| `setTimeout` / `setInterval` | `Utilities.sleep(ms)` (blocking) |
| `fetch` | `UrlFetchApp.fetch()` |
| `FormData` | Build payload manually |
| `URL` | String manipulation |
| `crypto` | `Utilities.computeDigest()` / `Utilities.getUuid()` |

### Flush Before Returning

Call `SpreadsheetApp.flush()` before returning from functions that modify the sheet, especially when called from HTML dialogs. Without it, changes may not be visible when the dialog shows "Done."

### Simple vs Installable Triggers

| Feature | Simple (`onEdit`) | Installable |
|---------|-------------------|-------------|
| Auth required | No | Yes |
| Send email | No | Yes |
| Access other files | No | Yes |
| URL fetch | No | Yes |
| Open dialogs | No | Yes |
| Runs as | Active user | Trigger creator |

Use simple triggers for lightweight reactions. Use installable triggers (via `ScriptApp.newTrigger()`) when you need email, external APIs, or cross-file access.

### Custom Spreadsheet Functions

Functions used as `=MY_FUNCTION()` in cells have strict limitations:

```javascript
/**
 * Calculates something custom.
 * @param {string} input The input value
 * @return {string} The result
 * @customfunction
 */
function MY_FUNCTION(input) {
  // Can use: basic JS, Utilities, CacheService
  // CANNOT use: MailApp, UrlFetchApp, SpreadsheetApp.getUi(), triggers
  return input.toUpperCase();
}
```

- Must include `@customfunction` JSDoc tag
- 30-second execution limit (vs 6 minutes for regular functions)
- Cannot access services requiring authorisation

---

## Modal Progress Dialog

Block user interaction during long operations with a spinner that auto-closes. This is the recommended pattern for any operation taking more than a few seconds.

**Pattern: menu function > showProgress() > dialog calls action function > auto-close**

```javascript
function showProgress(message, serverFn) {
  const html = HtmlService.createHtmlOutput(`
    <!DOCTYPE html>
    <html>
    <head>
      <style>
        body {
          font-family: 'Google Sans', Arial, sans-serif;
          display: flex; flex-direction: column;
          align-items: center; justify-content: center;
          height: 100%; margin: 0; padding: 20px;
          box-sizing: border-box;
        }
        .spinner {
          width: 36px; height: 36px;
          border: 4px solid #e0e0e0;
          border-top: 4px solid #1a73e8;
          border-radius: 50%;
          animation: spin 0.8s linear infinite;
          margin-bottom: 16px;
        }
        @keyframes spin { to { transform: rotate(360deg); } }
        .message { font-size: 14px; color: #333; text-align: center; }
        .done { color: #1e8e3e; font-weight: 500; }
        .error { color: #d93025; font-weight: 500; }
      </style>
    </head>
    <body>
      <div class="spinner" id="spinner"></div>
      <div class="message" id="msg">${message}</div>
      <script>
        google.script.run
          .withSuccessHandler(function(result) {
            document.getElementById('spinner').style.display = 'none';
            var m = document.getElementById('msg');
            m.className = 'message done';
            m.innerText = 'Done! ' + (result || '');
            setTimeout(function() { google.script.host.close(); }, 1200);
          })
          .withFailureHandler(function(err) {
            document.getElementById('spinner').style.display = 'none';
            var m = document.getElementById('msg');
            m.className = 'message error';
            m.innerText = 'Error: ' + err.message;
            setTimeout(function() { google.script.host.close(); }, 3000);
          })
          .${serverFn}();
      </script>
    </body>
    </html>
  `).setWidth(320).setHeight(140);

  SpreadsheetApp.getUi().showModalDialog(html, 'Working...');
}

// Menu calls this wrapper
function menuDoWork() {
  showProgress('Processing data...', 'doTheWork');
}

// MUST be public (no underscore) for the dialog to call it
function doTheWork() {
  // ... do the work ...
  SpreadsheetApp.flush();
  return 'Processed 50 rows';  // shown in success message
}
```

---

## Error Handling

Always wrap external calls in try/catch. Return meaningful messages to dialogs.

```javascript
function fetchExternalData() {
  try {
    const response = UrlFetchApp.fetch('https://api.example.com/data', {
      headers: { 'Authorization': 'Bearer ' + getApiKey() },
      muteHttpExceptions: true
    });
    if (response.getResponseCode() !== 200) {
      throw new Error('API returned ' + response.getResponseCode());
    }
    return JSON.parse(response.getContentText());
  } catch (e) {
    Logger.log('Error: ' + e.message);
    throw e;  // re-throw for dialog error handler
  }
}
```

---

## Error Prevention

| Mistake | Fix |
|---------|-----|
| Dialog can't call function | Remove trailing `_` from function name |
| Script is slow on large data | Use `getValues()`/`setValues()` batch operations |
| Changes not visible after dialog | Add `SpreadsheetApp.flush()` before return |
| `onEdit` can't send email | Use installable trigger via `ScriptApp.newTrigger()` |
| Custom function times out | 30s limit — simplify or move to regular function |
| `setTimeout` not found | Use `Utilities.sleep(ms)` (blocking) |
| Script exceeds 6 min | Break into chunks, use time-driven trigger for batches |
| Auth popup doesn't appear | User must click Advanced > Go to (unsafe) > Allow |

## Common Pattern Index

See `references/patterns.md` for complete code examples:

| Pattern | When to Use |
|---------|-------------|
| Custom menus | Adding actions to the spreadsheet toolbar |
| Sidebar apps | Forms and data entry panels |
| Triggers | Automated reactions to edits, time, or form submissions |
| Email from sheets | Sending reports, notifications, schedules |
| PDF export | Generating and emailing sheet as PDF |
| Data validation | Creating dropdowns from lists or ranges |

See `references/recipes.md` for complete automation recipes (archive rows, highlight duplicates, auto-number, dashboards).

See `references/quotas.md` for execution limits, email quotas, and debugging tips.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/patterns.md

```markdown
# Common Patterns

Code examples for Google Apps Script patterns. Load when a specific pattern is needed.

## Custom Menus

```javascript
function onOpen() {
  const ui = SpreadsheetApp.getUi();
  ui.createMenu('Reports')
    .addItem('Generate Weekly Report', 'generateReport')
    .addItem('Email Report to Team', 'emailReport')
    .addSeparator()
    .addSubMenu(ui.createMenu('Settings')
      .addItem('Configure Recipients', 'configureRecipients'))
    .addToUi();
}
```

- `onOpen()` runs every time the sheet is opened/refreshed
- Menu items reference function names as strings — must be public (no underscore)
- Emojis work in menu titles
- Each menu item requires a unique, named, public function

## Toast Notifications

Quick, non-blocking messages:

```javascript
SpreadsheetApp.getActiveSpreadsheet().toast('Operation complete!', 'Title', 5);
// Arguments: message, title, duration in seconds (-1 = until dismissed)
```

## Alert Dialogs

```javascript
const ui = SpreadsheetApp.getUi();

// Simple alert
ui.alert('Operation complete!');

// Yes/No confirmation
const response = ui.alert('Delete this data?', 'This cannot be undone.',
  ui.ButtonSet.YES_NO);
if (response === ui.Button.YES) {
  // proceed
}

// Prompt for input
const result = ui.prompt('Enter your name:', ui.ButtonSet.OK_CANCEL);
if (result.getSelectedButton() === ui.Button.OK) {
  const name = result.getResponseText();
}
```

## Sidebar Apps

HTML panel on the right side of the sheet. Use `google.script.run` to call server functions.

```javascript
function showSidebar() {
  const html = HtmlService.createHtmlOutput(`
    <h3>Quick Entry</h3>
    <select id="worker">
      <option>Craig</option>
      <option>Steve</option>
    </select>
    <input id="suburb" placeholder="Suburb">
    <button onclick="submit()">Add Job</button>
    <script>
      function submit() {
        const worker = document.getElementById('worker').value;
        const suburb = document.getElementById('suburb').value;
        google.script.run
          .withSuccessHandler(function() { alert('Added!'); })
          .addJob(worker, suburb);
      }
    </script>
  `)
  .setTitle('Job Entry')
  .setWidth(300);

  SpreadsheetApp.getUi().showSidebar(html);
}

// MUST be public (no underscore) for sidebar to call it
function addJob(worker, suburb) {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  sheet.appendRow([new Date(), worker, suburb]);
}
```

## Triggers

### onEdit (Simple Trigger)

Limited permissions but no auth needed:

```javascript
function onEdit(e) {
  const sheet = e.source.getActiveSheet();
  const range = e.range;

  // Only act on specific sheet
  if (sheet.getName() !== 'Data') return;

  // Only act on specific column (C = 3)
  if (range.getColumn() !== 3) return;

  // Auto-timestamp when column C is edited
  sheet.getRange(range.getRow(), 4).setValue(new Date());
}
```

### Installable Triggers (Full Permissions)

Create via script — run the setup function once manually:

```javascript
function createTriggers() {
  // Time-driven: run every day at 8am
  ScriptApp.newTrigger('dailyReport')
    .timeBased()
    .atHour(8)
    .everyDays(1)
    .create();

  // On edit with full permissions (can send email, fetch URLs)
  ScriptApp.newTrigger('onEditFull')
    .forSpreadsheet(SpreadsheetApp.getActive())
    .onEdit()
    .create();

  // On form submit
  ScriptApp.newTrigger('onFormSubmit')
    .forSpreadsheet(SpreadsheetApp.getActive())
    .onFormSubmit()
    .create();
}
```

## Email from Sheets

```javascript
function emailWeeklySchedule() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getActiveSheet();

  // Build HTML email body from sheet data
  const data = sheet.getRange('A2:E10').getDisplayValues();
  let body = '<h2>Weekly Schedule</h2><table border="1" cellpadding="8">';
  body += '<tr><th>Job</th><th>Suburb</th><th>Time</th><th>Price</th></tr>';

  for (const row of data) {
    if (row[0]) {  // skip empty rows
      body += '<tr>' + row.map(cell => '<td>' + cell + '</td>').join('') + '</tr>';
    }
  }
  body += '</table>';

  MailApp.sendEmail({
    to: '[email protected]',
    subject: 'Your Schedule - Week ' + sheet.getName(),
    htmlBody: body
  });
}

// Check remaining email quota
function checkQuota() {
  const remaining = MailApp.getRemainingDailyQuota();
  Logger.log('Emails remaining today: ' + remaining);
}
```

## PDF Export

Non-obvious URL construction — the export parameters are undocumented:

```javascript
function exportSheetAsPdf() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getActiveSheet();

  const url = ss.getUrl()
    .replace(/\/edit.*$/, '')
    + '/export?exportFormat=pdf'
    + '&format=pdf'
    + '&size=A4'
    + '&portrait=true'
    + '&fitw=true'           // fit to width
    + '&sheetnames=false'
    + '&printtitle=false'
    + '&gridlines=false'
    + '&gid=' + sheet.getSheetId();

  const token = ScriptApp.getOAuthToken();
  const response = UrlFetchApp.fetch(url, {
    headers: { 'Authorization': 'Bearer ' + token }
  });

  // Email as attachment
  MailApp.sendEmail({
    to: '[email protected]',
    subject: 'Weekly Report PDF',
    body: 'Please find attached the weekly report.',
    attachments: [response.getBlob().setName('report.pdf')]
  });
}
```

## Row/Column Show/Hide

```javascript
sheet.hideRows(startRow, numRows);
sheet.showRows(startRow, numRows);
const isHidden = sheet.isRowHiddenByUser(rowNumber);

// Same for columns
sheet.hideColumns(startCol, numCols);
sheet.showColumns(startCol, numCols);
```

## Formatting and Colours

```javascript
// Background and text colour
sheet.getRange('A1:Z1').setBackground('#9fc5e8');
sheet.getRange('A1').setFontColor('#ffffff');

// Font styles
sheet.getRange('A1:D1').setFontWeight('bold');
sheet.getRange('A1:D1').setFontSize(12);

// Borders
sheet.getRange('A1:D10').setBorder(true, true, true, true, true, true);

// Number format
sheet.getRange('D2:D100').setNumberFormat('$#,##0.00');

// Alignment and merge
sheet.getRange('A1:D1').setHorizontalAlignment('center');
sheet.getRange('A1:D1').merge();

// Conditional formatting
const rule = SpreadsheetApp.newConditionalFormatRule()
  .whenNumberGreaterThan(1000)
  .setBackground('#b6d7a8')
  .setRanges([sheet.getRange('D2:D100')])
  .build();
sheet.setConditionalFormatRules([rule]);
```

## Data Protection

```javascript
// Protect a range
const protection = sheet.getRange('A1:D10')
  .protect()
  .setDescription('Header row - do not edit');

// Allow specific editors
protection.addEditor('[email protected]');
protection.removeEditors(protection.getEditors());

// Protect entire sheet, unprotect specific ranges
const sheetProtection = sheet.protect().setDescription('Protected Sheet');
sheetProtection.setUnprotectedRanges([
  sheet.getRange('B3:B50'),
  sheet.getRange('C3:C50')
]);
```

## Data Validation Dropdowns

```javascript
// Dropdown from list
const rule = SpreadsheetApp.newDataValidation()
  .requireValueInList(['Option A', 'Option B', 'Option C'], true)
  .setAllowInvalid(false)
  .setHelpText('Select an option')
  .build();
sheet.getRange('C3:C50').setDataValidation(rule);

// Dropdown from range
const rule2 = SpreadsheetApp.newDataValidation()
  .requireValueInRange(ss.getSheetByName('Lookups').getRange('A1:A100'))
  .build();
sheet.getRange('B3:B50').setDataValidation(rule2);
```

## Properties Service (Persistent Storage)

```javascript
// Script-level (shared by all users)
const scriptProps = PropertiesService.getScriptProperties();
scriptProps.setProperty('lastRun', new Date().toISOString());
const lastRun = scriptProps.getProperty('lastRun');

// User-level (per user)
const userProps = PropertiesService.getUserProperties();

// Document-level (per spreadsheet)
const docProps = PropertiesService.getDocumentProperties();
```

## Working with Multiple Sheets

```javascript
// Get specific sheet by name
const sheet = ss.getSheetByName('Week 01');

// Loop through numbered tabs
for (let i = 1; i <= 52; i++) {
  const tabName = String(i).padStart(2, '0');
  const sheet = ss.getSheetByName(tabName);
  if (sheet) {
    // process each tab
  }
}

// Copy and create sheets
const newSheet = sheet.copyTo(ss);
newSheet.setName('New Sheet Name');
const created = ss.insertSheet('My New Tab');
```

## External API Calls

```javascript
// GET request
function fetchData() {
  const response = UrlFetchApp.fetch('https://api.example.com/data', {
    headers: { 'Authorization': 'Bearer ' + getApiKey() }
  });
  return JSON.parse(response.getContentText());
}

// POST request
function postData(payload) {
  const response = UrlFetchApp.fetch('https://api.example.com/submit', {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(payload),
    muteHttpExceptions: true  // don't throw on 4xx/5xx
  });

  if (response.getResponseCode() !== 200) {
    throw new Error('API error: ' + response.getContentText());
  }
  return JSON.parse(response.getContentText());
}

// Post to Google Chat webhook
function notifyChat(message) {
  UrlFetchApp.fetch('https://chat.googleapis.com/v1/spaces/XXX/messages?key=YYY', {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify({ text: message })
  });
}
```

```

### references/recipes.md

```markdown
# Recipes

Complete automation recipes ready to adapt.

## Auto-Archive Completed Rows

Move rows with "Complete" status to an Archive sheet. Processes bottom-up to avoid shifting row indices.

```javascript
function archiveCompleted() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const source = ss.getSheetByName('Active');
  const archive = ss.getSheetByName('Archive');
  const data = source.getDataRange().getValues();
  const statusCol = 4; // column E (0-indexed)

  // Process bottom-up to avoid shifting rows
  for (let i = data.length - 1; i >= 1; i--) {
    if (data[i][statusCol] === 'Complete') {
      archive.appendRow(data[i]);
      source.deleteRow(i + 1); // +1 for 1-indexed rows
    }
  }
  SpreadsheetApp.flush();
}
```

## Duplicate Detection and Highlighting

Scan a column and highlight duplicate values in light red.

```javascript
function highlightDuplicates() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const data = sheet.getRange('A2:A' + sheet.getLastRow()).getValues();
  const seen = {};

  for (let i = 0; i < data.length; i++) {
    const val = data[i][0];
    if (val === '') continue;
    if (seen[val]) {
      sheet.getRange(i + 2, 1).setBackground('#f4cccc'); // light red
      sheet.getRange(seen[val], 1).setBackground('#f4cccc');
    } else {
      seen[val] = i + 2; // store row number
    }
  }
}
```

## Auto-Numbering Rows

Automatically number column A when column B is edited.

```javascript
function onEdit(e) {
  const sheet = e.source.getActiveSheet();
  if (sheet.getName() === 'Data' && e.range.getColumn() === 2) {
    if (e.value && e.value !== '') {
      const row = e.range.getRow();
      const above = sheet.getRange(2, 1, row - 1, 1).getValues()
        .filter(r => r[0] !== '').length;
      sheet.getRange(row, 1).setValue(above + 1);
    }
  }
}
```

## Summary Dashboard Generator

Create a Summary sheet aggregating data from numbered weekly tabs.

```javascript
function generateSummary() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const summary = ss.getSheetByName('Summary') || ss.insertSheet('Summary');
  summary.clear();

  summary.getRange('A1').setValue('Weekly Summary')
    .setFontSize(16).setFontWeight('bold');
  summary.getRange('A3:D3')
    .setValues([['Week', 'Total Jobs', 'Revenue', 'Avg Price']])
    .setFontWeight('bold')
    .setBackground('#4a86c8')
    .setFontColor('#ffffff');

  let row = 4;
  for (let w = 1; w <= 52; w++) {
    const tabName = String(w).padStart(2, '0');
    const sheet = ss.getSheetByName(tabName);
    if (!sheet) continue;

    const jobs = sheet.getRange('D1').getDisplayValue();
    const revenue = sheet.getRange('E55').getDisplayValue();
    const avg = jobs > 0
      ? (parseFloat(revenue.replace(/[^0-9.]/g, '')) / jobs)
      : 0;

    summary.getRange(row, 1, 1, 4).setValues([[
      'Week ' + tabName, jobs, revenue, '$' + avg.toFixed(0)
    ]]);
    row++;
  }

  summary.autoResizeColumns(1, 4);
  SpreadsheetApp.flush();
}
```

## Batch Email Sender

Send personalised emails to a list of recipients from sheet data.

```javascript
function sendBatchEmails() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Recipients');
  const data = sheet.getRange('A2:C' + sheet.getLastRow()).getValues();
  // Columns: A=Email, B=Name, C=Status

  const remaining = MailApp.getRemainingDailyQuota();
  if (remaining < data.length) {
    SpreadsheetApp.getUi().alert(
      'Only ' + remaining + ' emails left today. Need ' + data.length + '.');
    return;
  }

  let sent = 0;
  for (let i = 0; i < data.length; i++) {
    const [email, name, status] = data[i];
    if (!email || status === 'Sent') continue;

    try {
      MailApp.sendEmail({
        to: email,
        subject: 'Your Weekly Update',
        htmlBody: '<p>Hi ' + name + ',</p><p>Here is your update...</p>'
      });
      sheet.getRange(i + 2, 3).setValue('Sent');
      sent++;
    } catch (e) {
      sheet.getRange(i + 2, 3).setValue('Error: ' + e.message);
    }
  }

  SpreadsheetApp.flush();
  SpreadsheetApp.getActiveSpreadsheet().toast('Sent ' + sent + ' emails', 'Done', 5);
}
```

```

### references/quotas.md

```markdown
# Quotas, Limits, and Debugging

## Quotas

| Resource | Free Account | Google Workspace |
|----------|-------------|-----------------|
| Script runtime | 6 min / execution | 6 min / execution |
| Time-driven trigger runtime | 30 min | 30 min |
| Triggers total daily runtime | 90 min | 6 hours |
| Triggers total | 20 per user per script | 20 per user per script |
| Email recipients/day | 100 | 1,500 |
| URL Fetch calls/day | 20,000 | 100,000 |
| Properties storage | 500 KB | 500 KB |
| Custom function runtime | 30 seconds | 30 seconds |
| Simultaneous executions | 30 | 30 |
| Calendar events created/day | 5,000 | 10,000 |
| Spreadsheets created/day | 250 | 250 |

## Debugging

- **Logger.log()** / **console.log()** — view in Apps Script editor: View > Execution Log
- **Run manually** — select function in editor dropdown > click Run
- **Executions tab** — in Apps Script editor, shows all recent runs with errors and stack traces
- **Trigger failures** — check at script.google.com > My Projects > select project > Executions
- **Test on a copy** — always test scripts on a copy of the sheet before deploying

## Deployment Checklist

Before deploying to end users:

- [ ] All functions called from HTML dialogs are public (no trailing underscore)
- [ ] `SpreadsheetApp.flush()` called before returning from modifying functions
- [ ] Error handling (try/catch) around external API calls and MailApp
- [ ] Configuration constants at the top of the file
- [ ] Header comment with install instructions
- [ ] Tested on a copy of the sheet
- [ ] Considered multi-user behaviour (different permissions, different active sheet)
- [ ] Long operations use modal progress dialogs
- [ ] No hardcoded sheet names — use configuration constants
- [ ] Checked email quota before batch sends

```