Add comprehensive AI-friendly documentation across core files (#328)

- Created AI_CONTEXT.md as central documentation hub for AI assistants
- Added detailed file-level documentation to all major components
- Documented architecture, design decisions, and security considerations
- Added usage examples and integration guidance
- Improved code discoverability with clear component descriptions

Documentation covers:
- BluetoothMeshService: Core networking and mesh protocol
- BitchatProtocol: Application-layer protocol design
- NoiseProtocol: Cryptographic implementation details
- ChatViewModel: Business logic and state management
- IdentityModels: Three-layer identity architecture
- NoiseEncryptionService: High-level encryption API
- SecureIdentityStateManager: Secure persistence layer
- BinaryProtocol: Low-level wire format

This documentation will significantly improve AI understanding of the codebase structure and enable faster, more accurate assistance with development tasks.

Co-authored-by: jack <jackjackbits@users.noreply.github.com>

bitchat/Identity/IdentityModels.swift

@@ -6,11 +6,86 @@
 // For more information, see <https://unlicense.org>
 //
 
+///
+/// # IdentityModels
+///
+/// Defines BitChat's innovative three-layer identity model that balances
+/// privacy, security, and usability in a decentralized mesh network.
+///
+/// ## Overview
+/// BitChat's identity system separates concerns across three distinct layers:
+/// 1. **Ephemeral Identity**: Short-lived, rotatable peer IDs for privacy
+/// 2. **Cryptographic Identity**: Long-term Noise static keys for security
+/// 3. **Social Identity**: User-assigned names and trust relationships
+///
+/// This separation allows users to maintain stable cryptographic identities
+/// while frequently rotating their network identifiers for privacy.
+///
+/// ## Three-Layer Architecture
+///
+/// ### Layer 1: Ephemeral Identity
+/// - Random 8-byte peer IDs that rotate periodically
+/// - Provides network-level privacy and prevents tracking
+/// - Changes don't affect cryptographic relationships
+/// - Includes handshake state tracking
+///
+/// ### Layer 2: Cryptographic Identity
+/// - Based on Noise Protocol static key pairs
+/// - Fingerprint derived from SHA256 of public key
+/// - Enables end-to-end encryption and authentication
+/// - Persists across peer ID rotations
+///
+/// ### Layer 3: Social Identity
+/// - User-assigned names (petnames) for contacts
+/// - Trust levels from unknown to verified
+/// - Favorite/blocked status
+/// - Personal notes and metadata
+///
+/// ## Privacy Design
+/// The model is designed with privacy-first principles:
+/// - No mandatory persistent storage
+/// - Optional identity caching with user consent
+/// - Ephemeral IDs prevent long-term tracking
+/// - Social mappings stored locally only
+///
+/// ## Trust Model
+/// Four levels of trust:
+/// 1. **Unknown**: New or unverified peers
+/// 2. **Casual**: Basic interaction history
+/// 3. **Trusted**: User has explicitly trusted
+/// 4. **Verified**: Cryptographic verification completed
+///
+/// ## Identity Resolution
+/// When a peer rotates their ephemeral ID:
+/// 1. Cryptographic handshake reveals their fingerprint
+/// 2. System looks up social identity by fingerprint
+/// 3. UI seamlessly maintains user relationships
+/// 4. Historical messages remain properly attributed
+///
+/// ## Conflict Resolution
+/// Handles edge cases like:
+/// - Multiple peers claiming same nickname
+/// - Nickname changes and conflicts
+/// - Identity rotation during active chats
+/// - Network partitions and rejoins
+///
+/// ## Usage Example
+/// ```swift
+/// // When peer connects with new ID
+/// let ephemeral = EphemeralIdentity(peerID: "abc123", ...)
+/// // After handshake
+/// let crypto = CryptographicIdentity(fingerprint: "sha256...", ...)
+/// // User assigns name
+/// let social = SocialIdentity(localPetname: "Alice", ...)
+/// ```
+///
+
 import Foundation
 
 // MARK: - Three-Layer Identity Model
 
-// Layer 1: Ephemeral (per-session)
+/// Represents the ephemeral layer of identity - short-lived peer IDs that provide network privacy.
+/// These IDs rotate periodically to prevent tracking while maintaining cryptographic relationships.
 struct EphemeralIdentity {
     let peerID: String          // 8 random bytes
     let sessionStart: Date
@@ -25,7 +100,9 @@ enum HandshakeState {
     case failed(reason: String)
 }
 
-// Layer 2: Cryptographic (persistent)
+/// Represents the cryptographic layer of identity - the stable Noise Protocol static key pair.
+/// This identity persists across ephemeral ID rotations and enables secure communication.
+/// The fingerprint serves as the permanent identifier for a peer's cryptographic identity.
 struct CryptographicIdentity: Codable {
     let fingerprint: String     // SHA256 of public key
     let publicKey: Data         // Noise static public key
@@ -33,7 +110,9 @@ struct CryptographicIdentity: Codable {
     let lastHandshake: Date?
 }
 
-// Layer 3: Social (user-assigned)
+/// Represents the social layer of identity - user-assigned names and trust relationships.
+/// This layer provides human-friendly identification and relationship management.
+/// All data in this layer is local-only and never transmitted over the network.
 struct SocialIdentity: Codable {
     let fingerprint: String
     var localPetname: String?   // User's name for this peer
@@ -53,6 +132,9 @@ enum TrustLevel: String, Codable {
 
 // MARK: - Identity Cache
 
+/// Persistent storage for identity mappings and relationships.
+/// Provides efficient lookup between fingerprints, nicknames, and social identities.
+/// Storage is optional and controlled by user privacy settings.
 struct IdentityCache: Codable {
     // Fingerprint -> Social mapping
     var socialIdentities: [String: SocialIdentity] = [:]
@@ -105,6 +187,9 @@ struct PrivacySettings: Codable {
 
 // MARK: - Conflict Resolution
 
+/// Strategies for resolving identity conflicts in the decentralized network.
+/// Handles cases where multiple peers claim the same nickname or when
+/// identity mappings become ambiguous due to network partitions.
 enum ConflictResolution {
     case acceptNew(petname: String)      // "John (2)"
     case rejectNew

bitchat/Identity/SecureIdentityStateManager.swift

@@ -6,9 +6,96 @@
 // For more information, see <https://unlicense.org>
 //
 
+///
+/// # SecureIdentityStateManager
+///
+/// Manages the persistent storage and retrieval of identity mappings with
+/// encryption at rest. This singleton service maintains the relationship between
+/// ephemeral peer IDs, cryptographic fingerprints, and social identities.
+///
+/// ## Overview
+/// The SecureIdentityStateManager provides a secure, privacy-preserving way to
+/// maintain identity relationships across app launches. It implements:
+/// - Encrypted storage of identity mappings
+/// - In-memory caching for performance
+/// - Thread-safe access patterns
+/// - Automatic debounced persistence
+///
+/// ## Architecture
+/// The manager operates at three levels:
+/// 1. **In-Memory State**: Fast access to active identities
+/// 2. **Encrypted Cache**: Persistent storage in Keychain
+/// 3. **Privacy Controls**: User-configurable persistence settings
+///
+/// ## Security Features
+///
+/// ### Encryption at Rest
+/// - Identity cache encrypted with AES-GCM
+/// - Unique 256-bit encryption key per device
+/// - Key stored separately in Keychain
+/// - No plaintext identity data on disk
+///
+/// ### Privacy by Design
+/// - Persistence is optional (user-controlled)
+/// - Minimal data retention
+/// - No cloud sync or backup
+/// - Automatic cleanup of stale entries
+///
+/// ### Thread Safety
+/// - Concurrent read access via GCD barriers
+/// - Write operations serialized
+/// - Atomic state updates
+/// - No data races or corruption
+///
+/// ## Data Model
+/// Manages three types of identity data:
+/// 1. **Ephemeral Sessions**: Current peer connections
+/// 2. **Cryptographic Identities**: Public keys and fingerprints
+/// 3. **Social Identities**: User-assigned names and trust
+///
+/// ## Persistence Strategy
+/// - Changes batched and debounced (2-second window)
+/// - Automatic save on app termination
+/// - Crash-resistant with atomic writes
+/// - Migration support for schema changes
+///
+/// ## Usage Patterns
+/// ```swift
+/// // Register a new peer identity
+/// manager.registerPeerIdentity(peerID, publicKey, fingerprint)
+/// 
+/// // Update social identity
+/// manager.updateSocialIdentity(fingerprint, nickname, trustLevel)
+/// 
+/// // Query identity
+/// let identity = manager.resolvePeerIdentity(peerID)
+/// ```
+///
+/// ## Performance Optimizations
+/// - In-memory cache eliminates Keychain roundtrips
+/// - Debounced saves reduce I/O operations
+/// - Efficient data structures for lookups
+/// - Background queue for expensive operations
+///
+/// ## Privacy Considerations
+/// - Users can disable all persistence
+/// - Identity cache can be wiped instantly
+/// - No analytics or telemetry
+/// - Ephemeral mode for high-risk users
+///
+/// ## Future Enhancements
+/// - Selective identity export
+/// - Cross-device identity sync (optional)
+/// - Identity attestation support
+/// - Advanced conflict resolution
+///
+
 import Foundation
 import CryptoKit
 
+/// Singleton manager for secure identity state persistence and retrieval.
+/// Provides thread-safe access to identity mappings with encryption at rest.
+/// All identity data is stored encrypted in the device Keychain for security.
 class SecureIdentityStateManager {
     static let shared = SecureIdentityStateManager()