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