From 126b9cf3187670274cea560ae6d73fd51bb245d4 Mon Sep 17 00:00:00 2001
From: Matt Bruce <mbrucedogs@gmail.com>
Date: Wed, 14 Jan 2026 12:14:16 -0600
Subject: [PATCH] Docs: update docs for Proposal, README

Summary:
- Docs: update docs for Proposal, README

Stats:
- 2 files changed, 18 insertions(+), 6 deletions(-)
---
 Proposal.md | 22 ++++++++++++++++------
 README.md   |  2 ++
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/Proposal.md b/Proposal.md
index 7a51e7c..2520422 100644
--- a/Proposal.md
+++ b/Proposal.md
@@ -20,31 +20,41 @@ Create a single, typed, discoverable namespace for persisted app data with consi
 - **StorageKey** protocol - Defines storage configuration for each data type
 - **StorageRouter** actor - Main entry point coordinating all storage operations
 - **StorageProviding** protocol - Abstraction for storage operations
+- **StorageKeyCatalog** protocol - Catalog of keys for auditing/validation
 
 ### Isolated Helper Classes (Actors)
 Each helper is a dedicated actor providing thread-safe access to a specific storage domain:
 
 - **KeychainHelper** - All keychain operations (set, get, delete, exists, deleteAll)
-- **EncryptionHelper** - AES-256-GCM encryption with PBKDF2 key derivation
-- **FileStorageHelper** - File system operations (read, write, delete, list, size)
-- **UserDefaultsHelper** - UserDefaults operations with suite support
+- **EncryptionHelper** - AES-256-GCM or ChaCha20-Poly1305 with PBKDF2/HKDF
+- **FileStorageHelper** - File system operations (read, write, delete, list, size), including App Group containers
+- **UserDefaultsHelper** - UserDefaults operations with suite and App Group support
 - **SyncHelper** - WatchConnectivity sync operations
 
 ### Models
-- **StorageDomain** - userDefaults, keychain, fileSystem, encryptedFileSystem
-- **SecurityPolicy** - none, keychain (with accessibility/accessControl), encrypted (AES-256)
-- **Serializer** - JSON, property list, raw Data, or custom encode/decode
+- **StorageDomain** - userDefaults, appGroupUserDefaults, keychain, fileSystem, encryptedFileSystem, appGroupFileSystem
+- **SecurityPolicy** - none, keychain (with accessibility/accessControl), encrypted (AES-256 or ChaCha20-Poly1305)
+- **Serializer** - JSON, property list, raw Data, or custom encode/decode with named serializer metadata
+- **KeyMaterialSource** - Identifier for external key material providers
 - **PlatformAvailability** - all, phoneOnly, watchOnly, phoneWithWatchSync
 - **SyncPolicy** - never, manual, automaticSmall
 - **KeychainAccessibility** - All 7 iOS options (whenUnlocked, afterFirstUnlock, etc.)
 - **KeychainAccessControl** - All 6 options (userPresence, biometryAny, devicePasscode, etc.)
 - **FileDirectory** - documents, caches, custom URL
 - **StorageError** - Comprehensive error types
+- **StorageKeyDescriptor** - Audit snapshot of a key’s storage metadata
+- **AnyStorageKey** - Type-erased storage key for catalogs
 - **AnyCodable** - Type-erased Codable for mixed-type payloads
 
 ## Usage Pattern
 Apps extend StorageKeys with their own key types and use StorageRouter.shared. This follows the Notification.Name pattern for discoverable keys.
 
+## Audit & Validation
+Apps can register a `StorageKeyCatalog` to generate audit reports and enforce key registration. Registration validates:
+- Duplicate key names
+- Missing descriptions
+- Unregistered keys at runtime (debug assertions)
+
 ## Sync Behavior
 StorageRouter can call WCSession.updateApplicationContext for manual or automaticSmall sync policies when availability allows it. Session activation and receiving data are owned by the app.
 
diff --git a/README.md b/README.md
index 66fe559..620bae6 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,8 @@ App Group storage is explicit via `StorageDomain.appGroupUserDefaults` and `Stor
 
 Use standard `userDefaults` or `fileSystem` for data that should remain scoped to a single target, even when App Groups are configured.
 
+For app-level configuration (App Group identifiers, keychain service identifiers, etc.), centralize constants in a shared module so keys do not hardcode string literals.
+
 ## Security Options
 
 ### Keychain Accessibility