From 8368900f492b6e82e75c3c60c3ba068d50ce9c3a Mon Sep 17 00:00:00 2001
From: Matt Bruce <mbrucedogs@gmail.com>
Date: Wed, 14 Jan 2026 13:51:14 -0600
Subject: [PATCH] Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

---
 README.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index fb5a88a..3fecfce 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,14 @@ These helpers are internal implementation details used by `StorageRouter`. They
 - **UserDefaultsHelper** - Wraps UserDefaults and suites safely.
 - **SyncHelper** - Manages WatchConnectivity sync.
 
-### Models
+### Global Configuration Models
+These are used at app lifecycle start to tune library engine behaviors:
+- **StorageConfiguration** - Default Keychain service and App Group IDs
+- **EncryptionConfiguration** - Global encryption settings (Keychain identifiers, key length)
+- **SyncConfiguration** - Global sync settings (Max automatic sync size)
+- **FileStorageConfiguration** - Global file settings (Sub-directory scoping)
+
+### Other Models
 - **StorageDomain** - userDefaults, appGroupUserDefaults, keychain, fileSystem, encryptedFileSystem, appGroupFileSystem
 - **SecurityPolicy** - none, keychain, encrypted (AES-256 or ChaCha20-Poly1305)
 - **Serializer** - JSON, plist, Data, or custom
@@ -46,9 +53,6 @@ These helpers are internal implementation details used by `StorageRouter`. They
 - **FileDirectory** - documents, caches, custom URL
 - **StorageError** - Comprehensive error types
 - **StorageKeyDescriptor** - Audit snapshot of a key’s storage metadata
-- **EncryptionConfiguration** - Global encryption settings (Keychain identifiers, key length)
-- **SyncConfiguration** - Global sync settings (Max automatic sync size)
-- **FileStorageConfiguration** - Global file settings (Custom folder names)
 - **AnyStorageKey** - Type-erased storage key for catalogs
 - **AnyCodable** - Type-erased Codable for mixed-type payloads
 
@@ -192,6 +196,22 @@ This will result in paths like:
 > [!WARNING]
 > Changing the `subDirectory` in an existing app will cause the library to look in the new location. Existing files in the old location will not be automatically moved.
 
+#### Global Storage Defaults
+
+To avoid repeating the same Keychain service or App Group identifier in every key, you can set library-wide defaults:
+
+```swift
+let storageConfig = StorageConfiguration(
+    defaultKeychainService: "com.myapp.keychain",
+    defaultAppGroupIdentifier: "group.com.myapp"
+)
+await StorageRouter.shared.updateStorageConfiguration(storageConfig)
+```
+
+When defaults are set, you can define keys using `nil` for these identifiers:
+- `.keychain(service: nil)` -> Uses "com.myapp.keychain"
+- `.appGroupUserDefaults(identifier: nil)` -> Uses "group.com.myapp"
+
 ```swift
 struct RemoteKeyProvider: KeyMaterialProviding {
     func keyMaterial(for keyName: String) async throws -> Data {