docs: move architecture and API docs to docs/ directory

Move design and API documentation to dedicated docs/ folder:
- ArchitecturalAudit.md — Audit of correctness issues in V2
- CorrectRaftStateMachinePattern.md — V3 migration design and rationale
- DESIGN.md — Original design blueprint
- API_DESIGN.md — HTTP API design
- API_USAGE_EXAMPLES.md — HTTP API usage examples

Update mix.exs to reference docs/ paths in docs.extras and package.files.
Remove outdated performance and analysis documents (pre-V3 benchmarks).
Update CLAUDE.md with V3 correctness invariants and architecture overview.

Author: GSMLG-BOT

docs/API_DESIGN.md

@@ -0,0 +1,281 @@
+# Concord HTTP API Design
+
+## Overview
+RESTful HTTP API for Concord distributed key-value store with JSON request/response format.
+
+## Base URL
+```
+http://localhost:4000/api/v1
+```
+
+## Authentication
+Two authentication methods supported:
+1. **Bearer Token**: `Authorization: Bearer <token>`
+2. **API Key**: `X-API-Key: <token>`
+
+Both use the existing Concord token system.
+
+## Endpoints
+
+### Core CRUD Operations
+
+#### PUT /api/v1/kv/{key}
+Store a single key-value pair.
+- **Method**: PUT
+- **Path**: `/api/v1/kv/{key}`
+- **Body**:
+  ```json
+  {
+    "value": "any JSON-serializable value",
+    "ttl": 3600  // optional, seconds
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "status": "ok"
+  }
+  ```
+
+#### GET /api/v1/kv/{key}
+Retrieve a single value.
+- **Method**: GET
+- **Path**: `/api/v1/kv/{key}`
+- **Query Params**:
+  - `with_ttl` (boolean): Include TTL information
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "value": "stored value",
+      "ttl": 3600  // only if with_ttl=true
+    }
+  }
+  ```
+
+#### DELETE /api/v1/kv/{key}
+Delete a single key.
+- **Method**: DELETE
+- **Path**: `/api/v1/kv/{key}`
+- **Response**:
+  ```json
+  {
+    "status": "ok"
+  }
+  ```
+
+### Bulk Operations
+
+#### POST /api/v1/kv/bulk
+Store multiple key-value pairs atomically.
+- **Method**: POST
+- **Path**: `/api/v1/kv/bulk`
+- **Body**:
+  ```json
+  {
+    "operations": [
+      {"key": "key1", "value": "value1"},
+      {"key": "key2", "value": "value2", "ttl": 3600}
+    ]
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "key1": "ok",
+      "key2": "ok"
+    }
+  }
+  ```
+
+#### POST /api/v1/kv/bulk/get
+Retrieve multiple values.
+- **Method**: POST
+- **Path**: `/api/v1/kv/bulk/get`
+- **Body**:
+  ```json
+  {
+    "keys": ["key1", "key2", "key3"],
+    "with_ttl": false
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "key1": {"status": "ok", "value": "value1"},
+      "key2": {"status": "error", "error": "not_found"},
+      "key3": {"status": "ok", "value": "value3", "ttl": 1800}
+    }
+  }
+  ```
+
+#### POST /api/v1/kv/bulk/delete
+Delete multiple keys atomically.
+- **Method**: POST
+- **Path**: `/api/v1/kv/bulk/delete`
+- **Body**:
+  ```json
+  {
+    "keys": ["key1", "key2", "key3"]
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "key1": "ok",
+      "key2": "ok",
+      "key3": {"status": "error", "error": "not_found"}
+    }
+  }
+  ```
+
+### TTL Operations
+
+#### POST /api/v1/kv/{key}/touch
+Extend TTL for a key.
+- **Method**: POST
+- **Path**: `/api/v1/kv/{key}/touch`
+- **Body**:
+  ```json
+  {
+    "ttl": 3600  // additional TTL seconds
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "status": "ok"
+  }
+  ```
+
+#### POST /api/v1/kv/bulk/touch
+Extend TTL for multiple keys.
+- **Method**: POST
+- **Path**: `/api/v1/kv/bulk/touch`
+- **Body**:
+  ```json
+  {
+    "operations": [
+      {"key": "key1", "ttl": 3600},
+      {"key": "key2", "ttl": 7200}
+    ]
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "key1": "ok",
+      "key2": "ok"
+    }
+  }
+  ```
+
+#### GET /api/v1/kv/{key}/ttl
+Get remaining TTL for a key.
+- **Method**: GET
+- **Path**: `/api/v1/kv/{key}/ttl`
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "ttl": 3600
+    }
+  }
+  ```
+
+### Administrative Operations
+
+#### GET /api/v1/kv
+Get all key-value pairs (use sparingly).
+- **Method**: GET
+- **Path**: `/api/v1/kv`
+- **Query Params**:
+  - `with_ttl` (boolean): Include TTL information
+  - `limit` (integer): Limit number of results
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "key1": {"value": "value1", "ttl": 3600},
+      "key2": {"value": "value2"}
+    }
+  }
+  ```
+
+#### GET /api/v1/health
+Health check endpoint.
+- **Method**: GET
+- **Path**: `/api/v1/health`
+- **Response**:
+  ```json
+  {
+    "status": "healthy",
+    "timestamp": "2025-01-20T12:00:00Z",
+    "cluster": {
+      "status": "leader",
+      "nodes": 3,
+      "storage": {
+        "size": 1000,
+        "memory": 1048576
+      }
+    }
+  }
+  ```
+
+#### GET /api/v1/status
+Detailed cluster status.
+- **Method**: GET
+- **Path**: `/api/v1/status`
+- **Response**:
+  ```json
+  {
+    "status": "ok",
+    "data": {
+      "cluster": {...},
+      "storage": {...},
+      "node": "node@hostname"
+    }
+  }
+  ```
+
+## Error Responses
+
+All error responses follow this format:
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "INVALID_KEY",
+    "message": "Key cannot be empty",
+    "details": {...}
+  }
+}
+```
+
+### Common Error Codes
+- `INVALID_REQUEST` - Malformed JSON or missing required fields
+- `INVALID_KEY` - Invalid key format
+- `UNAUTHORIZED` - Missing or invalid authentication
+- `NOT_FOUND` - Key does not exist
+- `TIMEOUT` - Operation timed out
+- `CLUSTER_UNAVAILABLE` - Cluster not ready
+- `BATCH_TOO_LARGE` - Batch exceeds size limits
+- `VALIDATION_ERROR` - Input validation failed
+
+## Rate Limiting
+- Configurable rate limits per API key
+- Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+
+## CORS
+- Configurable CORS policies for cross-origin requests