---

name: apple-notes-prod-checklist description: 'Production checklist for Apple Notes automation deployments.

Trigger: "apple notes production checklist".

' allowed-tools: Read, Write, Edit, Bash(osascript:*), Grep version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• macos
• apple-notes
• automation compatibility: Designed for Claude Code

---

Apple Notes Production Checklist

Overview

Before deploying Apple Notes automation to a production macOS machine, validate every dependency: TCC permissions, iCloud sync health, Notes.app availability, error handling robustness, and data security. Unlike cloud services where deployment is a push, Apple Notes automation requires physical or remote access to a Mac with a logged-in user session. This checklist ensures nothing is missed before going live.

Prerequisites

• An owned, interactive macOS host with the target account and an approved automation consent path.
• A documented backup and restore exercise for the specific notes and folders the automation may change.
• A non-production test folder or account for any write-path verification; production validation must be read-only by default.

Instructions

1. Complete the checklist on the exact host and user context that will run the automation.
2. Verify only the account and folders explicitly in scope; do not enumerate or export unrelated notes.
3. Treat a failed authorization, sync, or backup check as a deployment stop, not a warning.
4. Run a write-path test only in the designated test folder, confirm cleanup manually, and retain no note body in logs.

Pre-Deployment Checklist

Permissions and Access

• TCC automation permission granted (System Settings > Privacy > Automation)
• Permission tested from the exact context that will run in production (Terminal, launchd, etc.)
• Full Disk Access granted if reading Notes database directly (not recommended)
• Script runs without interactive prompts (no "Allow" dialogs left)

Application Configuration

• Notes.app configured to launch at login (System Settings > General > Login Items)
• Target Apple ID / iCloud account signed in and syncing
• "On My Mac" account enabled if local storage is needed
• Correct default account set for automation scripts

Data and Sync

• iCloud sync verified working (create note on Mac, verify on iPhone)
• Backup strategy documented (JSON export on schedule)
• Exported data files have restricted permissions (chmod 600)
• No sensitive data written to logs or temp files

Reliability

• Error handling for all AppleEvent failure codes (-1743, -1712, -609, -1728)
• Retry logic with exponential backoff for transient failures
• Write operations throttled (max 1 per second for iCloud sync)
• Health check script deployed and running on schedule
• Alerting configured for automation failures (macOS notification or webhook)

Compatibility

• Script tested on target macOS version (sw_vers)
• JXA API compatibility verified for target OS (Ventura/Sonoma/Sequoia)
• Node.js version matches production (if using child_process for osascript)

Validation Script

#!/bin/bash
echo "=== Apple Notes Production Readiness ==="
PASS=0; FAIL=0; WARN=0

check() {
  local label=$1 result=$2
  if [ "$result" = "PASS" ]; then echo "[PASS] $label"; PASS=$((PASS+1))
  elif [ "$result" = "WARN" ]; then echo "[WARN] $label"; WARN=$((WARN+1))
  else echo "[FAIL] $label"; FAIL=$((FAIL+1)); fi
}

# macOS version
VER=$(sw_vers -productVersion)
check "macOS version ($VER)" "$(echo "$VER" | grep -qE '^1[3-9]|^[2-9]' && echo PASS || echo WARN)"

# Notes.app running
check "Notes.app running" "$(pgrep -x Notes > /dev/null && echo PASS || echo FAIL)"

# JXA access
NOTE_COUNT=$(osascript -l JavaScript -e 'Application("Notes").defaultAccount.notes.length' 2>/dev/null)
check "JXA access (${NOTE_COUNT:-0} notes)" "$([ -n "$NOTE_COUNT" ] && echo PASS || echo FAIL)"

# iCloud sync daemon
check "iCloud sync daemon (bird)" "$(pgrep -x bird > /dev/null && echo PASS || echo WARN)"

# Keep readiness validation read-only. Exercise writes separately in a named,
# non-production test folder with an operator present and a verified cleanup plan.

echo ""
echo "=== Results: $PASS passed, $WARN warnings, $FAIL failed ==="
[ "$FAIL" -gt 0 ] && echo "BLOCKED: Fix failures before deploying" && exit 1
[ "$WARN" -gt 0 ] && echo "READY with warnings" && exit 0
echo "READY for production" && exit 0

Error Handling

Issue	Cause	Solution
Validation passes locally, fails on target Mac	Different macOS version or Apple ID	Run validation script on the exact production machine
Write test fails	Account is read-only (Gmail IMAP)	Switch to iCloud or "On My Mac" account
Notes.app not at login items	Removed after macOS update	Re-add via System Settings > General > Login Items
Health check does not alert	Notification permissions denied for Terminal	Grant notification permission in System Settings
iCloud sync lag in production	Large attachment uploads	Monitor with brctl status; set expectations for sync delay

Output

The readiness run prints a pass/warn/fail summary without note contents, IDs, or account identifiers. A non-zero exit means the deployment is blocked. Store only the timestamp, host inventory identifier, and checklist decision in the change record.

Examples

Before a scheduled deployment, run the read-only validation script from the launch context and attach its redacted summary to the change record. If write verification is needed, create and clean up a note in the pre-approved test folder during a supervised maintenance window; do not use a default account folder as a test target.

Resources

• Mac Automation Scripting Guide
• macOS Login Items
• Apple System Status

Next Steps

For deploying as a launchd service, see apple-notes-deploy-integration. For ongoing monitoring, see apple-notes-observability.