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/Protocols/BinaryProtocol.swift

@@ -6,6 +6,88 @@
 // For more information, see <https://unlicense.org>
 //
 
+///
+/// # BinaryProtocol
+///
+/// Low-level binary encoding and decoding for BitChat protocol messages.
+/// Optimized for Bluetooth LE's limited bandwidth and MTU constraints.
+///
+/// ## Overview
+/// BinaryProtocol implements an efficient binary wire format that minimizes
+/// overhead while maintaining extensibility. It handles:
+/// - Compact binary encoding with fixed headers
+/// - Optional field support via flags
+/// - Automatic compression for large payloads
+/// - Endianness handling for cross-platform compatibility
+///
+/// ## Wire Format
+/// ```
+/// Header (Fixed 13 bytes):
+/// +--------+------+-----+-----------+-------+----------------+
+/// |Version | Type | TTL | Timestamp | Flags | PayloadLength  |
+/// |1 byte  |1 byte|1byte| 8 bytes   | 1 byte| 2 bytes        |
+/// +--------+------+-----+-----------+-------+----------------+
+///
+/// Variable sections:
+/// +----------+-------------+---------+------------+
+/// | SenderID | RecipientID | Payload | Signature  |
+/// | 8 bytes  | 8 bytes*    | Variable| 64 bytes*  |
+/// +----------+-------------+---------+------------+
+/// * Optional fields based on flags
+/// ```
+///
+/// ## Design Rationale
+/// The protocol is designed for:
+/// - **Efficiency**: Minimal overhead for small messages
+/// - **Flexibility**: Optional fields via flag bits
+/// - **Compatibility**: Network byte order (big-endian)
+/// - **Performance**: Zero-copy where possible
+///
+/// ## Compression Strategy
+/// - Automatic compression for payloads > 256 bytes
+/// - LZ4 algorithm for speed over ratio
+/// - Original size stored for decompression
+/// - Flag bit indicates compressed payload
+///
+/// ## Flag Bits
+/// - Bit 0: Has recipient ID (directed message)
+/// - Bit 1: Has signature (authenticated message)
+/// - Bit 2: Is compressed (LZ4 compression applied)
+/// - Bits 3-7: Reserved for future use
+///
+/// ## Size Constraints
+/// - Maximum packet size: 65,535 bytes (16-bit length field)
+/// - Typical packet size: < 512 bytes (BLE MTU)
+/// - Minimum packet size: 21 bytes (header + sender ID)
+///
+/// ## Encoding Process
+/// 1. Construct header with fixed fields
+/// 2. Set appropriate flags
+/// 3. Compress payload if beneficial
+/// 4. Append variable-length fields
+/// 5. Calculate and append signature if needed
+///
+/// ## Decoding Process
+/// 1. Validate minimum packet size
+/// 2. Parse fixed header
+/// 3. Extract flags and determine field presence
+/// 4. Parse variable fields based on flags
+/// 5. Decompress payload if compressed
+/// 6. Verify signature if present
+///
+/// ## Error Handling
+/// - Graceful handling of malformed packets
+/// - Clear error messages for debugging
+/// - No crashes on invalid input
+/// - Logging of protocol violations
+///
+/// ## Performance Notes
+/// - Allocation-free for small messages
+/// - Streaming support for large payloads
+/// - Efficient bit manipulation
+/// - Platform-optimized byte swapping
+///
+
 import Foundation
 
 extension Data {
@@ -18,21 +100,10 @@ extension Data {
     }
 }
 
-// Binary Protocol Format:
-// Header (Fixed 13 bytes):
-// - Version: 1 byte
-// - Type: 1 byte  
-// - TTL: 1 byte
-// - Timestamp: 8 bytes (UInt64)
-// - Flags: 1 byte (bit 0: hasRecipient, bit 1: hasSignature)
-// - PayloadLength: 2 bytes (UInt16)
-//
-// Variable sections:
-// - SenderID: 8 bytes (fixed)
-// - RecipientID: 8 bytes (if hasRecipient flag set)
-// - Payload: Variable length
-// - Signature: 64 bytes (if hasSignature flag set)
-
+/// Implements binary encoding and decoding for BitChat protocol messages.
+/// Provides static methods for converting between BitchatPacket objects and
+/// their binary wire format representation.
+/// - Note: All multi-byte values use network byte order (big-endian)
 struct BinaryProtocol {
     static let headerSize = 13
     static let senderIDSize = 8

bitchat/Protocols/BitchatProtocol.swift

@@ -6,12 +6,65 @@
 // For more information, see <https://unlicense.org>
 //
 
+///
+/// # BitchatProtocol
+///
+/// Defines the application-layer protocol for BitChat mesh networking, including
+/// message types, packet structures, and encoding/decoding logic.
+///
+/// ## Overview
+/// BitchatProtocol implements a binary protocol optimized for Bluetooth LE's
+/// constrained bandwidth and MTU limitations. It provides:
+/// - Efficient binary message encoding
+/// - Message fragmentation for large payloads
+/// - TTL-based routing for mesh networks
+/// - Privacy features like padding and timing obfuscation
+/// - Integration points for end-to-end encryption
+///
+/// ## Protocol Design
+/// The protocol uses a compact binary format to minimize overhead:
+/// - 1-byte message type identifier
+/// - Variable-length fields with length prefixes
+/// - Network byte order (big-endian) for multi-byte values
+/// - PKCS#7-style padding for privacy
+///
+/// ## Message Flow
+/// 1. **Creation**: Messages are created with type, content, and metadata
+/// 2. **Encoding**: Converted to binary format with proper field ordering
+/// 3. **Fragmentation**: Split if larger than BLE MTU (512 bytes)
+/// 4. **Transmission**: Sent via BluetoothMeshService
+/// 5. **Routing**: Relayed by intermediate nodes (TTL decrements)
+/// 6. **Reassembly**: Fragments collected and reassembled
+/// 7. **Decoding**: Binary data parsed back to message objects
+///
+/// ## Security Considerations
+/// - Message padding obscures actual content length
+/// - Timing obfuscation prevents traffic analysis
+/// - Integration with Noise Protocol for E2E encryption
+/// - No persistent identifiers in protocol headers
+///
+/// ## Message Types
+/// - **Announce/Leave**: Peer presence notifications
+/// - **Message**: User chat messages (broadcast or directed)
+/// - **Fragment**: Multi-part message handling
+/// - **Delivery/Read**: Message acknowledgments
+/// - **Noise**: Encrypted channel establishment
+/// - **Version**: Protocol compatibility negotiation
+///
+/// ## Future Extensions
+/// The protocol is designed to be extensible:
+/// - Reserved message type ranges for future use
+/// - Version negotiation for backward compatibility
+/// - Optional fields for new features
+///
+
 import Foundation
 import CryptoKit
 
 // MARK: - Message Padding
 
-// Privacy-preserving padding utilities
+/// Provides privacy-preserving message padding to obscure actual content length.
+/// Uses PKCS#7-style padding with random bytes to prevent traffic analysis.
 struct MessagePadding {
     // Standard block sizes for padding
     static let blockSizes = [256, 512, 1024, 2048]
@@ -79,6 +132,9 @@ struct MessagePadding {
 
 // MARK: - Message Types
 
+/// Defines all message types in the BitChat protocol.
+/// Each type has a unique identifier for efficient binary encoding.
+/// Types are grouped by function: user messages, protocol control, encryption, etc.
 enum MessageType: UInt8 {
     case announce = 0x01
     case leave = 0x03
@@ -144,13 +200,19 @@ enum LazyHandshakeState {
 
 // MARK: - Special Recipients
 
-// Special recipient ID for broadcast messages
+/// Defines special recipient identifiers used in the protocol.
+/// These magic values indicate broadcast or system-level recipients
+/// rather than specific peer IDs.
 struct SpecialRecipients {
     static let broadcast = Data(repeating: 0xFF, count: 8)  // All 0xFF = broadcast
 }
 
 // MARK: - Core Protocol Structures
 
+/// The core packet structure for all BitChat protocol messages.
+/// Encapsulates all data needed for routing through the mesh network,
+/// including TTL for hop limiting and optional encryption.
+/// - Note: Packets larger than BLE MTU (512 bytes) are automatically fragmented
 struct BitchatPacket: Codable {
     let version: UInt8
     let type: UInt8
@@ -209,7 +271,9 @@ struct BitchatPacket: Codable {
 
 // MARK: - Delivery Acknowledgments
 
-// Delivery acknowledgment structure
+/// Acknowledgment sent when a message is successfully delivered to a recipient.
+/// Provides delivery confirmation for reliable messaging and UI feedback.
+/// - Note: Only sent for direct messages, not broadcasts
 struct DeliveryAck: Codable {
     let originalMessageID: String
     let ackID: String
@@ -656,7 +720,10 @@ struct ProtocolNack: Codable {
 
 // MARK: - Peer Identity Rotation
 
-// Enhanced identity announcement with rotation support
+/// Announces a peer's cryptographic identity to enable secure communication.
+/// Contains the peer's Noise static public key and supports identity rotation
+/// by binding ephemeral peer IDs to stable cryptographic fingerprints.
+/// - Note: Critical for establishing end-to-end encrypted channels
 struct NoiseIdentityAnnouncement: Codable {
     let peerID: String               // Current ephemeral peer ID
     let publicKey: Data              // Noise static public key
@@ -1078,6 +1145,10 @@ enum DeliveryStatus: Codable, Equatable {
 
 // MARK: - Message Model
 
+/// Represents a user-visible message in the BitChat system.
+/// Handles both broadcast messages and private encrypted messages,
+/// with support for mentions, replies, and delivery tracking.
+/// - Note: This is the primary data model for chat messages
 class BitchatMessage: Codable {
     let id: String
     let sender: String