docs: add statistics API documentation

Document the extended /statistics endpoint with complete
response schema and field descriptions.

docs/features/statistics-api.md

@@ -0,0 +1,143 @@
+# Statistics API
+
+## `GET /statistics`
+
+Returns aggregated server statistics including compute resources, projects, nodes, and links.
+
+**Authentication:** Requires active user session
+
+**Method:** `GET`
+
+**URL:** `http://server:3080/v1/statistics`
+
+### Response
+
+```json
+{
+  "computes": [
+    {
+      "compute_id": "string",
+      "compute_name": "string",
+      "statistics": {
+        "memory_total": 16777216000,
+        "memory_free": 8000000000,
+        "memory_used": 8777216000,
+        "swap_total": 2147479552,
+        "swap_free": 1500000000,
+        "swap_used": 647279552,
+        "cpu_usage_percent": 45,
+        "memory_usage_percent": 52,
+        "swap_usage_percent": 30,
+        "disk_usage_percent": 67,
+        "load_average_percent": [12, 8, 5]
+      }
+    }
+  ],
+  "projects": {
+    "total": 5,
+    "opened": 3,
+    "closed": 2
+  },
+  "nodes": {
+    "total": 42,
+    "open_project_nodes": 30,
+    "closed_project_nodes": 12,
+    "by_type": {
+      "qemu": 20,
+      "docker": 12,
+      "dynamips": 6,
+      "vpcs": 4
+    },
+    "by_status": {
+      "started": 25,
+      "stopped": 12,
+      "suspended": 5
+    }
+  },
+  "links": {
+    "total": 38,
+    "capturing": 2
+  }
+}
+```
+
+### Field Descriptions
+
+#### `computes`
+
+Array of compute node statistics. Each compute reports:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `compute_id` | string | Unique identifier for the compute |
+| `compute_name` | string | Human-readable name |
+| `statistics` | object | Resource usage statistics |
+
+#### `computes[].statistics`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `memory_total` | integer | Total physical memory in bytes |
+| `memory_free` | integer | Free memory in bytes |
+| `memory_used` | integer | Used memory in bytes |
+| `swap_total` | integer | Total swap space in bytes |
+| `swap_free` | integer | Free swap space in bytes |
+| `swap_used` | integer | Used swap space in bytes |
+| `cpu_usage_percent` | integer | CPU usage percentage (0-100) |
+| `memory_usage_percent` | integer | Memory usage percentage (0-100) |
+| `swap_usage_percent` | integer | Swap usage percentage (0-100) |
+| `disk_usage_percent` | integer | Disk usage percentage for project directory (0-100) |
+| `load_average_percent` | integer[] | Load average as percentage per CPU core (1/5/15 min) |
+
+#### `projects`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | integer | Total number of projects |
+| `opened` | integer | Number of projects currently opened |
+| `closed` | integer | Number of projects currently closed |
+
+#### `nodes`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | integer | Total number of nodes across all projects |
+| `open_project_nodes` | integer | Nodes in opened projects (has real status) |
+| `closed_project_nodes` | integer | Nodes in closed projects (loaded from topology JSON, no status) |
+| `by_type` | object | Node count grouped by node type (qemu, docker, dynamips, etc.) |
+| `by_status` | object | Node count grouped by status (only for `open_project_nodes`) |
+
+**Note on `by_status`:** Status is a runtime attribute only available for nodes in opened projects. Closed projects store topology data in JSON format which does not include runtime status. Therefore `by_status` only reflects nodes from opened projects.
+
+Valid node statuses: `started`, `stopped`, `suspended`
+
+#### `links`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total` | integer | Total number of links across all projects |
+| `capturing` | integer | Number of links currently capturing packets |
+
+### Example Usage
+
+```bash
+# Get statistics
+curl -X GET http://localhost:3080/v1/statistics \
+  -H "Authorization: Bearer <token>"
+```
+
+### Dashboard Integration
+
+This API is designed for monitoring dashboards that need:
+
+- **System health**: CPU, memory, disk from `computes[].statistics`
+- **Project overview**: Project counts from `projects`
+- **Node inventory**: Node counts by type and status from `nodes`
+- **Capture monitoring**: Active capture sessions from `links.capturing`
+
+### Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Unauthorized - invalid or missing session |
+| 500 | Internal server error |