axiom-icloud-drive-ref

# iCloud Drive Reference

**Purpose**: Comprehensive reference for file-based iCloud sync using ubiquitous containers
**Availability**: iOS 5.0+ (basic), iOS 8.0+ (iCloud Drive), iOS 11.0+ (modern APIs)
**Context**: File-based cloud storage, not database (use CloudKit for structured data)

## When to Use This Skill

Use this skill when:
- Implementing document-based iCloud sync
- Syncing user files across devices
- Building document-based apps (like Pages, Numbers)
- Coordinating file access across processes
- Handling iCloud file conflicts
- Using NSUbiquitousKeyValueStore for preferences

**NOT for**: Structured data with relationships (use `axiom-cloudkit-ref` instead)

---

## Overview

**iCloud Drive is for FILE-BASED sync**, not structured data.

**Use when**:
- User creates/edits documents
- Files need to sync like Dropbox
- Document picker integration

**Don't use when**:
- Need queryable structured data (use CloudKit)
- Need relationships between records (use CloudKit)
- Small key-value preferences (use NSUbiquitousKeyValueStore)

---

## Ubiquitous Containers

### Getting Ubiquitous Container URL

```swift
// ✅ CORRECT: Get iCloud container
func getICloudContainerURL() -> URL? {
    // nil = use first container in entitlements
    return FileManager.default.url(
        forUbiquityContainerIdentifier: nil
    )
}

// ✅ Check if iCloud is available
if let iCloudURL = getICloudContainerURL() {
    print("iCloud available: \(iCloudURL)")
} else {
    print("iCloud not available (not signed in or no entitlement)")
}
```

### Container Structure

```
iCloud Container/
├── Documents/          # User-visible files (Files app)
│   └── MyApp/         # Your app's documents
├── Library/           # Hidden from user
│   ├── Application Support/
│   └── Caches/
```

### Saving to iCloud Drive

```swift
// ✅ CORRECT: Save document to iCloud
func saveToICloud(data: Data, filename: String) throws {
    guard let iCloudURL = FileManager.default.url(
        forUbiquityCon