docs: comprehensive API reference and cleanup

- Socket API: Document all 7 commands with request/response examples
  - list_devices, get_instantaneous_demand, get_device_data
  - get_network_info, get_history_data, plus unsupported commands
  - Add field-by-field explanations and unit conversion formulas

- HTTP API: Expand documentation with complete endpoint details
  - Authentication (HTTP Basic Auth) with curl examples
  - Document get_usage_data, get_device_list, get_instantaneous_demand
  - Include request/response examples in XML and JSON

- Clients API: Add comprehensive usage guide
  - Full Python examples for both Socket and HTTP clients
  - Comparison table: Socket vs HTTP (protocol, auth, speed, features)
  - Clear recommendations for when to use each approach

- Data Models: Complete reference with all fields documented
  - Document all 6 models: DeviceInfo, DeviceList, InstantaneousDemand
  - CurrentSummation, UsageData, NetworkInfo
  - Include JSON response examples and usage patterns
  - Explain computed properties and unit conversions

- Remove embedded agent reasoning from socket_api.md
  - Clean up parenthetical authentication discussion
  - Professional reference manual format throughout

Expands documentation from ~130 lines to 838 lines with 35+ code examples.

Author: eman

docs/api/clients.md

@@ -1,8 +1,15 @@
 # Clients API
 
-The `meter_reader` library provides two client implementations for the Eagle Gateway.
+The `meter_reader` library provides two client implementations for the EAGLE Gateway, each suited to different deployment scenarios and authentication requirements.
 
-## Base Client
+## Overview
+
+Both clients inherit from the abstract `EagleClient` base class, which defines the common interface for interacting with the gateway. Choose based on your gateway's network configuration and authentication setup:
+
+* **Socket API**: Fast, low-overhead XML-based communication (Port 5002)
+* **HTTP API**: Standard HTTP with JSON responses and authentication support (Port 80)
+
+## Base Client Interface
 
 ::: meter_reader.clients.base.EagleClient
     handler: python
@@ -14,9 +21,46 @@ The `meter_reader` library provides two client implementations for the Eagle Gat
         - get_network_info
         - get_current_summation
 
+All implementations must provide these methods, ensuring consistent behavior across protocols.
+
 ## Socket Client
 
-The `EagleSocketClient` communicates via the local XML API on port 5002. This is the traditional method for most integrations.
+The `EagleSocketClient` communicates via the raw TCP socket API on port 5002. This is the fastest and lowest-latency option, making it ideal for real-time monitoring and historical data queries.
+
+### Usage Example
+
+```python
+from meter_reader import EagleSocketClient
+
+# Connect to the gateway
+client = EagleSocketClient("192.168.1.100")
+
+# Get real-time demand
+demand = client.get_instantaneous_demand()
+print(f"Current Demand: {demand.panic_demand:.2f} kW")
+
+# Get total consumption
+summation = client.get_current_summation()
+print(f"Delivered: {summation.delivered_kwh:.2f} kWh")
+
+# List connected devices
+devices = client.list_devices()
+for device in devices.device_info:
+    print(f"Device: {device.device_mac_id}")
+
+# Get network status
+network = client.get_network_info()
+print(f"Link Strength: {network.link_strength}%")
+
+# Get historical data (last hour, 15-minute intervals)
+from datetime import datetime, timedelta, timezone
+history = client.get_history_data(
+    start_time=datetime.now(timezone.utc) - timedelta(hours=1),
+    frequency=0x384  # 15 minutes in seconds (900)
+)
+for entry in history:
+    print(f"{entry.timestamp}: {entry.delivered_kwh:.2f} kWh")
+```
 
 ::: meter_reader.clients.socket.EagleSocketClient
     handler: python
@@ -25,16 +69,71 @@ The `EagleSocketClient` communicates via the local XML API on port 5002. This is
         - __init__
         - list_devices
         - get_instantaneous_demand
+        - get_current_summation
+        - get_usage_data
+        - get_network_info
         - get_history_data
 
 ## HTTP Client
 
-The `EagleHttpClient` communicates via the local web interface API (`cgi_manager`) on port 80. This method uses JSON responses where possible and supports username/password authentication.
+The `EagleHttpClient` communicates via HTTP POST requests to the `/cgi-bin/cgi_manager` endpoint on port 80. Responses are returned as JSON. This client supports username/password authentication and is useful for deployments where HTTP is preferred over raw sockets.
+
+### Usage Example
+
+```python
+from meter_reader import EagleHttpClient
+
+# Connect with credentials
+client = EagleHttpClient(
+    "192.168.1.100",
+    username="admin",
+    password="password"
+)
+
+# Get usage data (combines demand and summation)
+usage = client.get_usage_data()
+print(f"Demand: {usage.demand} {usage.demand_units}")
+print(f"Delivered: {usage.summation_delivered} {usage.summation_units}")
+print(f"Meter Status: {usage.meter_status}")
+
+# List connected devices
+devices = client.list_devices()
+for device in devices.device_info:
+    print(f"Device MAC: {device.device_mac_id}")
+    print(f"Model ID: {device.model_id}")
+
+# Get demand (synthesized from usage data)
+demand = client.get_instantaneous_demand()
+print(f"Demand: {demand.demand:.2f}")
+
+# Get summation (synthesized from usage data)
+summation = client.get_current_summation()
+print(f"Total Delivered: {summation.delivered_kwh:.2f} kWh")
+```
 
 ::: meter_reader.clients.http.EagleHttpClient
     handler: python
     options:
       members:
         - __init__
-        - get_usage_data
         - list_devices
+        - get_usage_data
+        - get_instantaneous_demand
+        - get_current_summation
+
+## Choosing Between Socket and HTTP
+
+| Feature | Socket | HTTP |
+|---------|--------|------|
+| Protocol | TCP on port 5002 | HTTP POST on port 80 |
+| Data Format | XML | JSON |
+| Authentication | Optional, in XML payload | HTTP Basic Auth |
+| Speed | Fastest | Slightly higher latency |
+| Firewall Friendly | May require port 5002 | Standard HTTP port |
+| Real-time Monitoring | Excellent | Good |
+| Historical Queries | Native support | Limited |
+
+### Recommendation
+
+* Use **Socket API** if you need the lowest latency, historical data queries, or the device has port 5002 open
+* Use **HTTP API** if you need standard HTTP authentication, prefer JSON, or must operate within strict firewall rules