# Obsidian iCloud Sync

## Problem
The Obsidian vault lives in iCloud Drive and is not present on the local Linux machine.

## Detection
- Check `~` and `~/Documents` for the vault folder.
- If absent, the vault is remote (iCloud, OneDrive, Google Drive, Dropbox, etc.).

## Options for iCloud specifically

### Option 1: icloudpd / pyicloud (automated sync)
- Install: `pip3 install icloudpd pyicloud`
- **PITFALL**: pyicloud requires your **actual Apple ID password**, not an app-specific password.
  - App-specific passwords (e.g., for SMTP/IMAP) are rejected with `401 Unauthorized`.
  - If the user stores an app-specific password in `.env` (e.g., `APPLE_APP_PASSWORD`), it will NOT work for pyicloud.
- pyicloud also triggers 2FA/MFA on Apple devices during first login.
- Workflow: authenticate → list iCloud Drive root → locate vault folder → sync down → then use normal file tools.

### Option 2: Manual transfer (recommended if auth is problematic)
- User zips the vault from their Mac/phone and transfers it here (SFTP/SCP/Nextcloud).
- Agent works on the local copy; user syncs back via iCloud on their end.
- This avoids exposing the Apple ID password and dealing with 2FA.

### Option 3: Alternative sync layer
- If the user already uses Syncthing, Nextcloud, or similar, point the vault path there.

## Post-sync
Once the vault is local, use the standard Obsidian file-tool workflow (read_file, write_file, patch, search_files) with the resolved absolute path.