refactor: address PR review comments

- Clean up redundant envPrefix comments in ConfigurationKeys.swift
  - Added section-level docs explaining pattern once
  - Removed repetitive inline comments
  - Applied to all config enums for consistency

- Refactor pemString parameter to use Optional<String>
  - Changed SyncEngine.init() from String = "" to String? = nil
  - Updated logic from isEmpty check to if-let binding
  - Simplified SyncCommand call site (removed ?? "")
  - More idiomatic Swift, better expresses optional nature

- Update cron schedule to 3x daily with randomized times
  - Changed from every 12 hours to specific times:
    02:17, 10:43, 18:29 UTC (~8 hours apart)
  - Randomized minutes avoid predictable patterns
  - Aligns with VirtualBuddy TSS 12-hour cache

- Restructure workflow into separate build and sync jobs
  - Build job: Runs in Swift container, compiles binary
  - Sync job: Runs on native Ubuntu (no container overhead)
  - Only build needs Swift container (reduced CI minutes)
  - Better separation of concerns

Addresses review comments from @leogdion on PR #10

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: leogdion

.github/workflows/cloudkit-sync.yml

@@ -1,9 +1,12 @@
 name: Scheduled CloudKit Sync
 
 on:
-  # Run every 12 hours (00:00 and 12:00 UTC)
+  # Run three times daily (every ~8 hours) with randomized minutes
+  # Staggered to avoid predictable patterns and align with VirtualBuddy TSS cache (12h)
   schedule:
-    - cron: '0 */12 * * *'
+    - cron: '17 2 * * *'   # 02:17 UTC
+    - cron: '43 10 * * *'  # 10:43 UTC
+    - cron: '29 18 * * *'  # 18:29 UTC
 
   # Allow manual trigger for testing
   workflow_dispatch:
@@ -19,11 +22,11 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  sync:
-    name: Sync to CloudKit
+  build:
+    name: Build bushel-cloud
     runs-on: ubuntu-latest
     container: swift:6.2-noble
-    timeout-minutes: 30
+    timeout-minutes: 20
 
     permissions:
       contents: read  # Read repository code
@@ -54,13 +57,32 @@ jobs:
           echo "Binary location: $BIN_PATH/bushel-cloud"
           ls -lh "$BIN_PATH/bushel-cloud"
 
-      - name: Upload binary as artifact
+      - name: Upload binary for sync job
         uses: actions/upload-artifact@v4
         with:
-          name: bushel-cloud-${{ runner.os }}-${{ github.sha }}
+          name: bushel-cloud-binary
           path: ${{ steps.build.outputs.bin-path }}/bushel-cloud
-          retention-days: 7
-          if-no-files-found: warn
+          retention-days: 1  # Short retention, only needed for sync job
+          if-no-files-found: error
+
+  sync:
+    name: Sync to CloudKit
+    runs-on: ubuntu-latest  # No container needed - uses pre-built binary
+    needs: [build]
+    timeout-minutes: 30
+
+    permissions:
+      contents: read  # Read repository code
+
+    steps:
+      - name: Download built binary
+        uses: actions/download-artifact@v4
+        with:
+          name: bushel-cloud-binary
+          path: ./binary
+
+      - name: Make binary executable
+        run: chmod +x ./binary/bushel-cloud
 
       - name: Run CloudKit sync
         env:
@@ -73,13 +95,9 @@ jobs:
           echo "Container: $CLOUDKIT_CONTAINER_ID"
           echo "Environment: $CLOUDKIT_ENVIRONMENT"
 
-          # Use pre-built binary (already computed in build step)
-          BIN_PATH="${{ steps.build.outputs.bin-path }}"
-          echo "Using binary: $BIN_PATH/bushel-cloud"
-
           # Run pre-built binary
           # Note: Same key works for both development and production
           # Change CLOUDKIT_ENVIRONMENT to 'production' when ready
-          "$BIN_PATH/bushel-cloud" sync \
+          ./binary/bushel-cloud sync \
             --verbose \
             --container-identifier "$CLOUDKIT_CONTAINER_ID"

Sources/BushelCloudCLI/Commands/SyncCommand.swift

@@ -53,7 +53,7 @@ enum SyncCommand {
       containerIdentifier: config.cloudKit.containerID,
       keyID: config.cloudKit.keyID,
       privateKeyPath: config.cloudKit.privateKeyPath,
-      pemString: config.cloudKit.privateKey ?? "",      // Raw PEM if provided
+      pemString: config.cloudKit.privateKey,           // Raw PEM if provided (optional)
       environment: config.cloudKit.environment,         // Parsed environment enum
       configuration: fetchConfiguration
     )

Sources/BushelCloudKit/CloudKit/SyncEngine.swift

@@ -78,21 +78,21 @@ public struct SyncEngine: Sendable {
   ///   - containerIdentifier: CloudKit container ID
   ///   - keyID: Server-to-Server Key ID
   ///   - privateKeyPath: Path to .pem file (use if pemString not provided)
-  ///   - pemString: PEM content as string (use for CI/CD, takes priority over privateKeyPath)
+  ///   - pemString: PEM content as string (use for CI/CD, takes priority over privateKeyPath when non-nil)
   ///   - environment: CloudKit environment (.development or .production, defaults to .development)
   ///   - configuration: Fetch configuration for data sources
   /// - Throws: Error if authentication credentials are invalid or missing
   public init(
     containerIdentifier: String,
     keyID: String,
     privateKeyPath: String = "",
-    pemString: String = "",
+    pemString: String? = nil,
     environment: Environment = .development,
     configuration: FetchConfiguration = FetchConfiguration.loadFromEnvironment()
   ) throws {
     // Prefer PEM string if provided (CI/CD pattern), fall back to file path (local development)
     let service: BushelCloudKitService
-    if !pemString.isEmpty {
+    if let pemString = pemString {
       service = try BushelCloudKitService(
         containerIdentifier: containerIdentifier,
         keyID: keyID,

Sources/BushelCloudKit/Configuration/ConfigurationKeys.swift

@@ -35,11 +35,13 @@ internal enum ConfigurationKeys {
   // MARK: - CloudKit Configuration
 
   /// CloudKit configuration keys
+  ///
+  /// Uses `envPrefix: nil` to auto-generate environment variable names from the key path.
+  /// Example: "cloudkit.container_id" → ENV: CLOUDKIT_CONTAINER_ID
   internal enum CloudKit {
-    // Using base key with auto-generation (no prefix for CloudKit ENV vars)
     internal static let containerID = ConfigKey<String>(
       "cloudkit.container_id",
-      envPrefix: nil,  // Generates: CLI="cloudkit.container_id", ENV="CLOUDKIT_CONTAINER_ID"
+      envPrefix: nil,
       default: "iCloud.com.brightdigit.Bushel"
     )
 
@@ -55,32 +57,37 @@ internal enum ConfigurationKeys {
 
     internal static let privateKey = OptionalConfigKey<String>(
       "cloudkit.private_key",
-      envPrefix: nil  // Generates: ENV="CLOUDKIT_PRIVATE_KEY"
+      envPrefix: nil
     )
 
     internal static let environment = ConfigKey<String>(
       "cloudkit.environment",
-      envPrefix: nil,  // Generates: ENV="CLOUDKIT_ENVIRONMENT"
+      envPrefix: nil,
       default: "development"
     )
   }
 
   // MARK: - VirtualBuddy Configuration
 
   /// VirtualBuddy TSS API configuration keys
+  ///
+  /// Uses `envPrefix: nil` for auto-generated ENV names (VIRTUALBUDDY_API_KEY).
   internal enum VirtualBuddy {
     internal static let apiKey = OptionalConfigKey<String>(
       "virtualbuddy.api_key",
-      envPrefix: nil  // Generates: ENV="VIRTUALBUDDY_API_KEY"
+      envPrefix: nil
     )
   }
 
   // MARK: - Fetch Configuration
 
   /// Fetch throttling configuration keys
+  ///
+  /// Uses `bushelPrefixed:` to add BUSHEL_ prefix to all environment variables.
+  /// Example: "fetch.interval_global" → ENV: BUSHEL_FETCH_INTERVAL_GLOBAL
   internal enum Fetch {
     internal static let intervalGlobal = OptionalConfigKey<Double>(
-      bushelPrefixed: "fetch.interval_global"  // Generates: ENV="BUSHEL_FETCH_INTERVAL_GLOBAL"
+      bushelPrefixed: "fetch.interval_global"
     )
 
     /// Generate per-source interval key dynamically
@@ -90,14 +97,16 @@ internal enum ConfigurationKeys {
       let normalized = source.replacingOccurrences(of: ".", with: "_")
       return OptionalConfigKey<Double>(
         "fetch.interval.\(normalized)",
-        envPrefix: nil  // CLI: "fetch.interval.appledb_dev", ENV: "FETCH_INTERVAL_APPLEDB_DEV"
+        envPrefix: nil
       )
     }
   }
 
   // MARK: - Sync Command Configuration
 
-  /// Sync command configuration keys (using base key with BUSHEL prefix)
+  /// Sync command configuration keys
+  ///
+  /// Uses `bushelPrefixed:` for BUSHEL_SYNC_* environment variables.
   internal enum Sync {
     internal static let dryRun = ConfigKey<Bool>(bushelPrefixed: "sync.dry_run")
     internal static let restoreImagesOnly = ConfigKey<Bool>(
@@ -115,6 +124,8 @@ internal enum ConfigurationKeys {
   // MARK: - Export Command Configuration
 
   /// Export command configuration keys
+  ///
+  /// Uses `bushelPrefixed:` for BUSHEL_EXPORT_* environment variables.
   internal enum Export {
     internal static let output = OptionalConfigKey<String>(bushelPrefixed: "export.output")
     internal static let pretty = ConfigKey<Bool>(bushelPrefixed: "export.pretty")
@@ -126,6 +137,8 @@ internal enum ConfigurationKeys {
   // MARK: - Status Command Configuration
 
   /// Status command configuration keys
+  ///
+  /// Uses `bushelPrefixed:` for BUSHEL_STATUS_* environment variables.
   internal enum Status {
     internal static let errorsOnly = ConfigKey<Bool>(bushelPrefixed: "status.errors_only")
     internal static let detailed = ConfigKey<Bool>(bushelPrefixed: "status.detailed")
@@ -134,6 +147,8 @@ internal enum ConfigurationKeys {
   // MARK: - List Command Configuration
 
   /// List command configuration keys
+  ///
+  /// Uses `bushelPrefixed:` for BUSHEL_LIST_* environment variables.
   internal enum List {
     internal static let restoreImages = ConfigKey<Bool>(bushelPrefixed: "list.restore_images")
     internal static let xcodeVersions = ConfigKey<Bool>(bushelPrefixed: "list.xcode_versions")
@@ -143,6 +158,8 @@ internal enum ConfigurationKeys {
   // MARK: - Clear Command Configuration
 
   /// Clear command configuration keys
+  ///
+  /// Uses `bushelPrefixed:` for BUSHEL_CLEAR_* environment variables.
   internal enum Clear {
     internal static let yes = ConfigKey<Bool>(bushelPrefixed: "clear.yes")
     internal static let verbose = ConfigKey<Bool>(bushelPrefixed: "clear.verbose")