diff --git a/.agent/utils/generate_api_docs.py b/.agent/utils/generate_api_docs.py
new file mode 100644
index 0000000..81f93b2
--- /dev/null
+++ b/.agent/utils/generate_api_docs.py
@@ -0,0 +1,175 @@
+import sys
+import json
+import os
+import re
+
+from app.main import app
+
+def slugify(text):
+    return re.sub(r'[^a-zA-Z0-9]+', '-', text.lower()).strip('-')
+
+def generate_docs(openapi_schema):
+    paths = openapi_schema.get("paths", {})
+    components = openapi_schema.get("components", {}).get("schemas", {})
+    
+    groups = {}
+    
+    for path, methods in paths.items():
+        for method, spec in methods.items():
+            tags = spec.get("tags", [])
+            if tags and tags[0]:
+                group_name = tags[0]
+            else:
+                segments = [s for s in path.split('/') if s]
+                if segments:
+                    group_name = segments[0].capitalize()
+                else:
+                    group_name = "General"
+                    
+            if group_name not in groups:
+                groups[group_name] = []
+            
+            groups[group_name].append((path, method, spec))
+            
+    # Always write to project's doc directory
+    # If run from /app/.agent/utils, we need to go up to /app/ai-hub/docs
+    # Let's use absolute route or assume we are executed from inside /app/ai-hub
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    docs_dir = os.path.abspath(os.path.join(script_dir, "../../ai-hub/docs/api_reference"))
+    os.makedirs(docs_dir, exist_ok=True)
+    
+    index_md = "# API Reference\n\nThis API reference is grouped by feature:\n\n"
+    
+    for group_name, endpoints in groups.items():
+        file_name = f"{slugify(group_name)}.md"
+        index_md += f"- [{group_name}](./{file_name})\n"
+        
+        md = f"# API Reference: {group_name}\n\n"
+        
+        for path, method, spec in endpoints:
+            md += f"## {method.upper()} `{path}`\n\n"
+            summary = spec.get('summary', 'No summary provided.')
+            description = spec.get('description', summary)
+            
+            md += f"**Summary:** {summary}\n\n"
+            md += f"**Description:** {description}\n\n"
+            
+            parameters = spec.get("parameters", [])
+            has_user_id = False
+            query_params = []
+            if parameters:
+                md += "#### Parameters\n\n"
+                md += "| Name | In | Required | Type | Description |\n"
+                md += "|------|----|----------|------|-------------|\n"
+                for param in parameters:
+                    name = param.get("name", "")
+                    in_ = param.get("in", "")
+                    if in_.lower() == "header" and name.lower() == "x-user-id":
+                        has_user_id = True
+                    if in_.lower() == "query":
+                        query_params.append(f"{name}=<{name}>")
+                        
+                    required = "Yes" if param.get("required") else "No"
+                    schema = param.get("schema", {})
+                    p_type = schema.get("type", "any")
+                    if "anyOf" in schema:
+                        p_type = "anyOf"
+                    desc = param.get("description", "").replace('\n', ' ')
+                    md += f"| `{name}` | {in_} | {required} | {p_type} | {desc} |\n"
+                md += "\n"
+            
+            requestBody = spec.get("requestBody", {})
+            is_multipart = False
+            
+            if requestBody:
+                md += "#### Request Body\n\n"
+                required = "Yes" if requestBody.get("required") else "No"
+                md += f"**Required:** {required}\n\n"
+                if "description" in requestBody:
+                    md += f"{requestBody['description']}\n\n"
+                content = requestBody.get("content", {})
+                for media_type, media_schema in content.items():
+                    md += f"- **Media Type:** `{media_type}`\n"
+                    if "multipart/form-data" in media_type:
+                        is_multipart = True
+                    schema_ref = media_schema.get("schema", {})
+                    if "$ref" in schema_ref:
+                        ref_name = schema_ref["$ref"].split("/")[-1]
+                        md += f"- **Schema:** `{ref_name}` (Define in Models)\n"
+                md += "\n"
+                    
+            responses = spec.get("responses", {})
+            if responses:
+                md += "#### Responses\n\n"
+                md += "| Status Code | Description |\n"
+                md += "|-------------|-------------|\n"
+                for status_code, response_spec in responses.items():
+                    desc = response_spec.get('description', '')
+                    md += f"| `{status_code}` | {desc} |\n"
+                md += "\n"
+                
+            md += "#### Example Usage\n\n"
+            md += "```bash\n"
+            
+            full_path = f"http://localhost:8000/api/v1{path}"
+            if query_params:
+                full_path += "?" + "&".join(query_params)
+                
+            md += f"curl -X '{method.upper()}' \\\n"
+            md += f"  '{full_path}' \\\n"
+            md += f"  -H 'accept: application/json'"
+            
+            if has_user_id:
+                md += " \\\n  -H 'X-User-ID: <your_user_id>'"
+                
+            if requestBody and not is_multipart:
+                md += " \\\n  -H 'Content-Type: application/json' \\\n"
+                md += f"  -d '{{}}'"
+            elif is_multipart:
+                md += " \\\n  -H 'Content-Type: multipart/form-data' \\\n"
+                md += "  -F 'file=@/path/to/file'"
+                
+            md += "\n```\n\n"
+            md += "---\n\n"
+            
+        with open(os.path.join(docs_dir, file_name), "w") as f:
+            f.write(md)
+            
+    if components:
+        md = "# Models (Schemas)\n\n"
+        for name, schema in components.items():
+            md += f"## `{name}`\n\n"
+            md += f"**Type:** `{schema.get('type', 'object')}`\n\n"
+            if "description" in schema:
+                md += f"**Description:** {schema['description']}\n\n"
+            
+            properties = schema.get("properties", {})
+            if properties:
+                md += "| Property | Type | Description |\n"
+                md += "|----------|------|-------------|\n"
+                required_fields = schema.get("required", [])
+                for prop_name, prop_spec in properties.items():
+                    p_type = prop_spec.get("type", "")
+                    if "$ref" in prop_spec:
+                        p_type = "Ref: " + prop_spec["$ref"].split("/")[-1]
+                    if "anyOf" in prop_spec:
+                        p_type = "anyOf"
+                    req = "*" if prop_name in required_fields else ""
+                    desc = prop_spec.get("description", "").replace('\n', ' ')
+                    md += f"| `{prop_name}{req}` | `{p_type}` | {desc} |\n"
+                md += "\n"
+        
+        with open(os.path.join(docs_dir, "models.md"), "w") as f:
+            f.write(md)
+            
+        index_md += "- [Models (Schemas)](./models.md)\n"
+            
+    with open(os.path.join(docs_dir, "index.md"), "w") as f:
+        f.write(index_md)
+        
+    print(f"Documentation generated successfully at {docs_dir}!")
+
+if __name__ == "__main__":
+    # execute with python3 from within /app/ai-hub
+    schema = app.openapi()
+    generate_docs(schema)
diff --git a/.agent/workflows/deploy_to_production.md b/.agent/workflows/deploy_to_production.md
index 1552b54..79d8c4b 100644
--- a/.agent/workflows/deploy_to_production.md
+++ b/.agent/workflows/deploy_to_production.md
@@ -56,8 +56,12 @@
    - `OIDC_SERVER_URL=http://localhost:8080`
    - `OIDC_REDIRECT_URI=http://localhost:8002/api/v1/users/login/callback`
    *(Ensure these are mapped in your production deployment toolchain or manually placed on the server under `/home/coder/project/cortex-hub/.env`)*
-3. **Sync**: Sync local codebase to `/tmp/cortex-hub/` on the server.
-4. **Proto & Version Management**: 
+3. **Auto-Generate API Docs**: Before deploying, if any backend API changes have been made, regenerate the documentation:
+   ```bash
+   cd /app/ai-hub && python3 /app/.agent/utils/generate_api_docs.py
+   ```
+4. **Sync**: Sync local codebase to `/tmp/cortex-hub/` on the server.
+5. **Proto & Version Management**: 
    - If `ai-hub/app/protos/agent.proto` has changed, regenerate stubs:
      ```bash
      cd /app/ai-hub/app/protos && python3 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. agent.proto
diff --git a/README.md b/README.md
index 8da3f24..2fec2ce 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,17 @@
 └── docker-compose.yml  # Generic Development Entrypoint
 ```
 
+## 📚 API Documentation
+
+Cortex Hub APIs are self-documenting.
+* **Interactive Swagger UI**: When running the backend locally, navigate to [http://localhost:8000/docs](http://localhost:8000/docs).
+* **Static Markdown Reference**: The full API definition (including detailed endpoints, schemas, and `curl` examples) is generated statically from the FastAPI OpenAPI schema. You can view the grouped documentation at `ai-hub/docs/api_reference/index.md`. 
+
+If you make any changes to the backend APIs, regenerate the Markdown documentation by running:
+```bash
+cd ai-hub && python3 ../.agent/utils/generate_api_docs.py
+```
+
 ## 🧪 Testing
 
 *   **Backend**: `pytest ai-hub/tests/`
diff --git a/ai-hub/docs/api_reference/admin.md b/ai-hub/docs/api_reference/admin.md
new file mode 100644
index 0000000..ea38413
--- /dev/null
+++ b/ai-hub/docs/api_reference/admin.md
@@ -0,0 +1,256 @@
+# API Reference: Admin
+
+## PUT `/admin/config/oidc`
+
+**Summary:** Update OIDC Configuration
+
+**Description:** Update OIDC Configuration
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `OIDCConfigUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/admin/config/oidc' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## PUT `/admin/config/app`
+
+**Summary:** Update Application Configuration
+
+**Description:** Update Application Configuration
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `AppConfigUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/admin/config/app' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## POST `/admin/config/oidc/test`
+
+**Summary:** Test OIDC Discovery
+
+**Description:** Test OIDC Discovery
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `OIDCConfigUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/admin/config/oidc/test' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/admin/config/swarm/test/{nonce}`
+
+**Summary:** Echo Swarm Nonce
+
+**Description:** Echo Swarm Nonce
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `nonce` | path | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/admin/config/swarm/test/{nonce}' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/admin/config/swarm/test`
+
+**Summary:** Test Swarm Connection
+
+**Description:** Test Swarm Connection
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SwarmConfigUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/admin/config/swarm/test' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## PUT `/admin/config/swarm`
+
+**Summary:** Update Swarm Configuration
+
+**Description:** Update Swarm Configuration
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SwarmConfigUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/admin/config/swarm' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/admin/config`
+
+**Summary:** Get Admin Configuration
+
+**Description:** Get Admin Configuration
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/admin/config' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/agent-nodes.md b/ai-hub/docs/api_reference/agent-nodes.md
new file mode 100644
index 0000000..f08a24c
--- /dev/null
+++ b/ai-hub/docs/api_reference/agent-nodes.md
@@ -0,0 +1,860 @@
+# API Reference: Agent Nodes
+
+## POST `/nodes/admin`
+
+**Summary:** [Admin] Register New Node
+
+**Description:** Admin registers a new Agent Node.
+Returns the node record including a generated invite_token that must be
+placed in the node's config YAML before deployment.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `admin_id` | query | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `AgentNodeCreate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/admin?admin_id=<admin_id>' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/nodes/admin`
+
+**Summary:** [Admin] List All Nodes
+
+**Description:** Full node list for admin dashboard, including invite_token and skill config.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/admin?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/admin/{node_id}`
+
+**Summary:** [Admin] Get Node Detail
+
+**Description:** [Admin] Get Node Detail
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## PATCH `/nodes/admin/{node_id}`
+
+**Summary:** [Admin] Update Node Config
+
+**Description:** Update display_name, description, skill_config toggles, or is_active.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `AgentNodeUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PATCH' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}?admin_id=<admin_id>' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## DELETE `/nodes/admin/{node_id}`
+
+**Summary:** [Admin] Deregister Node
+
+**Description:** Delete a node registration and all its access grants.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/nodes/admin/{node_id}/access`
+
+**Summary:** [Admin] Grant Group Access
+
+**Description:** Grant a group access to use this node in sessions.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `NodeAccessGrant` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}/access?admin_id=<admin_id>' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## DELETE `/nodes/admin/{node_id}/access/{group_id}`
+
+**Summary:** [Admin] Revoke Group Access
+
+**Description:** [Admin] Revoke Group Access
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `group_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}/access/{group_id}?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/nodes/admin/mesh/reset`
+
+**Summary:** [Admin] Emergency Mesh Reset
+
+**Description:** DANGEROUS: Clears ALL live node collections from memory and resets DB statuses to offline.
+Use this to resolve 'zombie' nodes or flapping connections.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/admin/mesh/reset?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/`
+
+**Summary:** List Accessible Nodes
+
+**Description:** Returns nodes the calling user's group has access to.
+Merges live connection state from the in-memory registry.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `user_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/?user_id=<user_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/{node_id}/status`
+
+**Summary:** Quick Node Online Check
+
+**Description:** Quick Node Online Check
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/status' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## GET `/nodes/{node_id}/terminal`
+
+**Summary:** Read Node Terminal History (AI Use Case)
+
+**Description:** AI-Specific: Returns the most recent 150 terminal interaction chunks for a live node.
+This provides context for the AI reasoning agent.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/terminal' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/nodes/{node_id}/dispatch`
+
+**Summary:** Dispatch Task to Node
+
+**Description:** Queue a shell task to an online node.
+Emits task_assigned immediately so the live UI shows it.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `user_id` | query | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `NodeDispatchRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/dispatch?user_id=<user_id>' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## POST `/nodes/{node_id}/cancel`
+
+**Summary:** Cancel/Interrupt Task on Node
+
+**Description:** Sends a TaskCancelRequest to the specified node.
+For shell skills, this typically translates to SIGINT (Ctrl+C).
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `task_id` | query | No | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/cancel?task_id=<task_id>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## PATCH `/nodes/preferences`
+
+**Summary:** Update User Node Preferences
+
+**Description:** Save the user's default_node_ids and data_source config into their preferences.
+The UI reads this to auto-attach nodes when a new session starts.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `user_id` | query | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `UserNodePreferences` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PATCH' \
+  'http://localhost:8000/api/v1/nodes/preferences?user_id=<user_id>' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/nodes/preferences`
+
+**Summary:** Get User Node Preferences
+
+**Description:** Get User Node Preferences
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `user_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/preferences?user_id=<user_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/admin/{node_id}/config.yaml`
+
+**Summary:** [Admin] Download Node Config YAML
+
+**Description:** Generate and return the agent_config.yaml content an admin downloads
+and places alongside the node client software before deployment.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}/config.yaml?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/provision/{node_id}`
+
+**Summary:** Headless Provisioning Script
+
+**Description:** Returns a Python script that can be piped into python3 to automatically
+install and start the agent node.
+
+Usage: curl -sSL https://.../provision/{node_id}?token={token} | python3
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `token` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/provision/{node_id}?token=<token>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/admin/{node_id}/download`
+
+**Summary:** [Admin] Download Agent Node Bundle (ZIP)
+
+**Description:** Bundles the entire Agent Node source code along with a pre-configured
+agent_config.yaml into a single ZIP file for the user to download.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `admin_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/admin/{node_id}/download?admin_id=<admin_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/nodes/validate-token`
+
+**Summary:** [Internal] Validate Node Invite Token
+
+**Description:** Internal HTTP endpoint called by the gRPC SyncConfiguration handler
+to validate an invite_token before accepting a node connection.
+
+Returns the node's skill_config (sandbox policy) on success so the
+gRPC server can populate the SandboxPolicy response.
+
+Response:
+  200 { valid: true, node_id, skill_config, display_name }
+  401 { valid: false, reason }
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `token` | query | Yes | string |  |
+| `node_id` | query | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/validate-token?token=<token>&node_id=<node_id>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/nodes/{node_id}/fs/ls`
+
+**Summary:** List Directory Content
+
+**Description:** Request a directory listing from a node.
+Returns a tree-structured list for the File Navigator.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `path` | query | No | string |  |
+| `session_id` | query | No | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/fs/ls?path=<path>&session_id=<session_id>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## GET `/nodes/{node_id}/fs/cat`
+
+**Summary:** Read File Content
+
+**Description:** Read the content of a file on a remote node.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `path` | query | Yes | string |  |
+| `session_id` | query | No | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/fs/cat?path=<path>&session_id=<session_id>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/nodes/{node_id}/fs/touch`
+
+**Summary:** Create File or Directory
+
+**Description:** Create a new file or directory on the node.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `FileWriteRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/fs/touch' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/nodes/{node_id}/fs/download`
+
+**Summary:** Download File
+
+**Description:** Download a file from an agent node.
+Triggers a fetch to the hub's mirror, then serves it.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `path` | query | Yes | string |  |
+| `session_id` | query | No | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/fs/download?path=<path>&session_id=<session_id>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/nodes/{node_id}/fs/upload`
+
+**Summary:** Upload File
+
+**Description:** Upload a file to an agent node.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `path` | query | Yes | string |  |
+| `session_id` | query | No | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `multipart/form-data`
+- **Schema:** `Body_fs_upload_nodes__node_id__fs_upload_post` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/fs/upload?path=<path>&session_id=<session_id>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: multipart/form-data' \
+  -F 'file=@/path/to/file'
+```
+
+---
+
+## POST `/nodes/{node_id}/fs/rm`
+
+**Summary:** Delete File/Directory
+
+**Description:** Delete a file or directory from a remote node.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `node_id` | path | Yes | string |  |
+| `X-User-ID` | header | Yes | string |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `FileDeleteRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/nodes/{node_id}/fs/rm' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/agent-update.md b/ai-hub/docs/api_reference/agent-update.md
new file mode 100644
index 0000000..9c7a29c
--- /dev/null
+++ b/ai-hub/docs/api_reference/agent-update.md
@@ -0,0 +1,71 @@
+# API Reference: Agent Update
+
+## GET `/agent/version`
+
+**Summary:** Get current agent version
+
+**Description:** Returns the current agent-node version. Called by agent nodes at startup
+and periodically to detect if they need to self-update.
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/agent/version' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/agent/download`
+
+**Summary:** Download agent node tarball
+
+**Description:** Streams the current agent-node source as a gzipped tarball.
+Only called when an agent detects it is behind the hub's version.
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/agent/download' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/agent/installer`
+
+**Summary:** Download bootstrap_installer.py
+
+**Description:** Returns the bootstrap_installer.py script itself.
+Used for initial one-liner provisioning on headless nodes.
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/agent/installer' \
+  -H 'accept: application/json'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/documents.md b/ai-hub/docs/api_reference/documents.md
new file mode 100644
index 0000000..015a72a
--- /dev/null
+++ b/ai-hub/docs/api_reference/documents.md
@@ -0,0 +1,85 @@
+# API Reference: Documents
+
+## GET `/documents/`
+
+**Summary:** List All Documents
+
+**Description:** List All Documents
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/documents/' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/documents/`
+
+**Summary:** Add a New Document
+
+**Description:** Add a New Document
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `DocumentCreate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/documents/' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## DELETE `/documents/{document_id}`
+
+**Summary:** Delete a Document
+
+**Description:** Delete a Document
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `document_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/documents/{document_id}' \
+  -H 'accept: application/json'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/general.md b/ai-hub/docs/api_reference/general.md
new file mode 100644
index 0000000..69c7cb1
--- /dev/null
+++ b/ai-hub/docs/api_reference/general.md
@@ -0,0 +1,46 @@
+# API Reference: General
+
+## GET `/`
+
+**Summary:** Check Service Status
+
+**Description:** Check Service Status
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/status`
+
+**Summary:** Get Full System Status
+
+**Description:** Get Full System Status
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/status' \
+  -H 'accept: application/json'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/index.md b/ai-hub/docs/api_reference/index.md
new file mode 100644
index 0000000..c2bfd17
--- /dev/null
+++ b/ai-hub/docs/api_reference/index.md
@@ -0,0 +1,15 @@
+# API Reference
+
+This API reference is grouped by feature:
+
+- [General](./general.md)
+- [Sessions](./sessions.md)
+- [Documents](./documents.md)
+- [TTS](./tts.md)
+- [STT](./stt.md)
+- [Users](./users.md)
+- [Agent Nodes](./agent-nodes.md)
+- [Skills](./skills.md)
+- [Agent Update](./agent-update.md)
+- [Admin](./admin.md)
+- [Models (Schemas)](./models.md)
diff --git a/ai-hub/docs/api_reference/models.md b/ai-hub/docs/api_reference/models.md
new file mode 100644
index 0000000..fccfdfe
--- /dev/null
+++ b/ai-hub/docs/api_reference/models.md
@@ -0,0 +1,773 @@
+# Models (Schemas)
+
+## `AgentNodeAdminDetail`
+
+**Type:** `object`
+
+**Description:** Full node detail for admin view — includes invite_token and skill config.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_id*` | `string` |  |
+| `display_name*` | `string` |  |
+| `description` | `anyOf` |  |
+| `skill_config` | `object` |  |
+| `capabilities` | `object` |  |
+| `invite_token` | `anyOf` |  |
+| `is_active` | `boolean` |  |
+| `last_status*` | `string` |  |
+| `last_seen_at` | `anyOf` |  |
+| `created_at*` | `string` |  |
+| `registered_by*` | `string` |  |
+| `group_access` | `array` |  |
+| `stats` | `Ref: AgentNodeStats` |  |
+
+## `AgentNodeCreate`
+
+**Type:** `object`
+
+**Description:** Payload for admin creating a new node registration.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_id*` | `string` | Stable identifier used in the node's config YAML, e.g. 'dev-macbook-m3' |
+| `display_name*` | `string` | Human-readable name shown in the UI |
+| `description` | `anyOf` |  |
+| `skill_config` | `Ref: NodeSkillConfig` |  |
+
+## `AgentNodeStats`
+
+**Type:** `object`
+
+**Description:** Live performance stats reported via heartbeat.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `active_worker_count` | `integer` |  |
+| `cpu_usage_percent` | `number` |  |
+| `memory_usage_percent` | `number` |  |
+| `cpu_count` | `integer` |  |
+| `memory_used_gb` | `number` |  |
+| `memory_total_gb` | `number` |  |
+| `running` | `array` |  |
+| `cpu_usage_per_core` | `array` |  |
+| `cpu_freq_mhz` | `number` |  |
+| `memory_available_gb` | `number` |  |
+| `load_avg` | `array` |  |
+
+## `AgentNodeUpdate`
+
+**Type:** `object`
+
+**Description:** Payload for admin updating node configuration.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `display_name` | `anyOf` |  |
+| `description` | `anyOf` |  |
+| `skill_config` | `anyOf` |  |
+| `is_active` | `anyOf` |  |
+
+## `AgentNodeUserView`
+
+**Type:** `object`
+
+**Description:** Node as seen by a user — no invite_token, no admin config details.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_id*` | `string` |  |
+| `display_name*` | `string` |  |
+| `description` | `anyOf` |  |
+| `capabilities` | `object` |  |
+| `available_skills` | `array` |  |
+| `last_status*` | `string` |  |
+| `last_seen_at` | `anyOf` |  |
+| `stats` | `Ref: AgentNodeStats` |  |
+
+## `AppConfigUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `allow_password_login` | `anyOf` |  |
+
+## `Body_fs_upload_nodes__node_id__fs_upload_post`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `file*` | `string` |  |
+
+## `Body_import_user_config_yaml_users_me_config_import_post`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `file*` | `string` |  |
+
+## `Body_transcribe_audio_to_text_stt_transcribe_post`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `audio_file*` | `string` |  |
+
+## `Body_upload_message_audio_sessions_messages__message_id__audio_post`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `file*` | `string` |  |
+
+## `ChatRequest`
+
+**Type:** `object`
+
+**Description:** Defines the shape of a request to the /chat endpoint.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `prompt*` | `string` |  |
+| `provider_name` | `string` |  |
+| `load_faiss_retriever` | `anyOf` | Whether to use the FAISS DB retriever for the chat. |
+
+## `ConfigResponse`
+
+**Type:** `object`
+
+**Description:** Schema for returning user preferences alongside effective settings.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `preferences*` | `Ref: UserPreferences` |  |
+| `effective` | `object` |  |
+
+## `DirectoryListing`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_id*` | `string` |  |
+| `path*` | `string` |  |
+| `files*` | `array` |  |
+
+## `DocumentCreate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title*` | `string` |  |
+| `text*` | `string` |  |
+| `source_url` | `anyOf` |  |
+| `author` | `anyOf` |  |
+| `user_id` | `string` |  |
+
+## `DocumentDeleteResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `message*` | `string` |  |
+| `document_id*` | `integer` |  |
+
+## `DocumentInfo`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id*` | `integer` |  |
+| `title*` | `string` |  |
+| `source_url` | `anyOf` |  |
+| `status*` | `string` |  |
+| `created_at*` | `string` |  |
+
+## `DocumentListResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `documents*` | `array` |  |
+
+## `DocumentResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `message*` | `string` |  |
+
+## `FileDeleteRequest`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path*` | `string` |  |
+| `session_id` | `anyOf` |  |
+
+## `FileNodeInfo`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path*` | `string` |  |
+| `name*` | `string` |  |
+| `is_dir*` | `boolean` |  |
+| `size` | `integer` |  |
+| `hash` | `anyOf` |  |
+| `is_synced` | `boolean` |  |
+
+## `FileWriteRequest`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path*` | `string` |  |
+| `content` | `string` |  |
+| `is_dir` | `boolean` |  |
+| `session_id` | `anyOf` |  |
+
+## `GroupCreate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name*` | `string` |  |
+| `description` | `anyOf` |  |
+| `policy` | `object` |  |
+
+## `GroupInfo`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name*` | `string` |  |
+| `description` | `anyOf` |  |
+| `policy` | `object` |  |
+| `id*` | `string` |  |
+| `created_at` | `anyOf` |  |
+
+## `GroupUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `anyOf` |  |
+| `description` | `anyOf` |  |
+| `policy` | `anyOf` |  |
+
+## `HTTPValidationError`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `detail` | `array` |  |
+
+## `LocalLoginRequest`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `email*` | `string` |  |
+| `password*` | `string` |  |
+
+## `Message`
+
+**Type:** `object`
+
+**Description:** Defines the shape of a single message within a session's history.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id*` | `integer` |  |
+| `sender*` | `string` |  |
+| `content*` | `string` |  |
+| `reasoning_content` | `anyOf` |  |
+| `created_at*` | `string` |  |
+| `audio_url` | `anyOf` |  |
+| `has_audio` | `boolean` |  |
+
+## `MessageHistoryResponse`
+
+**Type:** `object`
+
+**Description:** Defines the response for retrieving a session's chat history.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `session_id*` | `integer` |  |
+| `messages*` | `array` |  |
+
+## `ModelInfoResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `model_name*` | `string` |  |
+| `max_tokens` | `anyOf` |  |
+| `max_input_tokens` | `anyOf` |  |
+
+## `NodeAccessGrant`
+
+**Type:** `object`
+
+**Description:** Admin grants a group access to a node.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `group_id*` | `string` |  |
+| `access_level` | `string` | 'view', 'use', or 'admin' |
+
+## `NodeAccessResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id*` | `integer` |  |
+| `node_id*` | `string` |  |
+| `group_id*` | `string` |  |
+| `access_level*` | `string` |  |
+| `granted_at*` | `string` |  |
+
+## `NodeAttachRequest`
+
+**Type:** `object`
+
+**Description:** Attach one or more nodes to a session.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_ids*` | `array` |  |
+| `config` | `anyOf` |  |
+
+## `NodeConfigYamlResponse`
+
+**Type:** `object`
+
+**Description:** The generated config YAML content an admin downloads to set up a node.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_id*` | `string` |  |
+| `config_yaml*` | `string` |  |
+
+## `NodeDataSourceConfig`
+
+**Type:** `object`
+
+**Description:** How a node should seed its workspace for a session.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `source` | `string` | 'empty' | 'server' | 'node_local' |
+| `path` | `anyOf` |  |
+
+## `NodeDispatchRequest`
+
+**Type:** `object`
+
+**Description:** Dispatch a shell action to a specific node.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `task_id` | `anyOf` |  |
+| `command` | `string` |  |
+| `session_id` | `anyOf` |  |
+| `timeout_ms` | `integer` |  |
+
+## `NodeDispatchResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `task_id*` | `string` |  |
+| `status*` | `string` |  |
+| `reason` | `anyOf` |  |
+
+## `NodeSkillConfig`
+
+**Type:** `object`
+
+**Description:** Admin-controlled skill configuration for a node.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `status` | `anyOf` |  |
+| `shell` | `Ref: SkillConfig` |  |
+| `sync` | `Ref: SkillConfig` |  |
+
+## `NodeSyncStatusEntry`
+
+**Type:** `object`
+
+**Description:** Per-node sync status within a session.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `node_id*` | `string` |  |
+| `status*` | `string` |  |
+| `last_sync` | `anyOf` |  |
+| `error` | `anyOf` |  |
+
+## `NodeWorkspaceConfig`
+
+**Type:** `object`
+
+**Description:** How a node should seed its workspace for a session.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `source` | `string` |  |
+| `path` | `anyOf` |  |
+| `source_node_id` | `anyOf` |  |
+| `read_only_node_ids` | `array` |  |
+
+## `OIDCConfigUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `anyOf` |  |
+| `client_id` | `anyOf` |  |
+| `client_secret` | `anyOf` |  |
+| `server_url` | `anyOf` |  |
+| `redirect_uri` | `anyOf` |  |
+| `allow_oidc_login` | `anyOf` |  |
+
+## `PasswordUpdateRequest`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `current_password*` | `string` |  |
+| `new_password*` | `string` |  |
+
+## `STTResponse`
+
+**Type:** `object`
+
+**Description:** Defines the shape of a successful response from the /stt endpoint.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `transcript*` | `string` |  |
+
+## `SandboxConfig`
+
+**Type:** `object`
+
+**Description:** Granular command execution policy for the shell skill.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mode` | `string` |  |
+| `allowed_commands` | `array` |  |
+| `denied_commands` | `array` |  |
+| `sensitive_commands` | `array` |  |
+
+## `Session`
+
+**Type:** `object`
+
+**Description:** Defines the shape of a session object returned by the API.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id*` | `integer` |  |
+| `user_id*` | `string` |  |
+| `title` | `anyOf` |  |
+| `provider_name` | `anyOf` |  |
+| `stt_provider_name` | `anyOf` |  |
+| `tts_provider_name` | `anyOf` |  |
+| `feature_name*` | `string` |  |
+| `created_at*` | `string` |  |
+| `sync_workspace_id` | `anyOf` |  |
+| `attached_node_ids` | `anyOf` |  |
+| `node_sync_status` | `anyOf` |  |
+| `sync_config` | `anyOf` |  |
+
+## `SessionCreate`
+
+**Type:** `object`
+
+**Description:** Defines the shape for starting a new conversation session.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `user_id*` | `string` |  |
+| `provider_name` | `string` |  |
+| `stt_provider_name` | `anyOf` |  |
+| `tts_provider_name` | `anyOf` |  |
+| `feature_name` | `anyOf` |  |
+
+## `SessionNodeStatusResponse`
+
+**Type:** `object`
+
+**Description:** Response showing all attached nodes and their sync state.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `session_id*` | `integer` |  |
+| `sync_workspace_id` | `anyOf` |  |
+| `nodes` | `array` |  |
+| `sync_config` | `anyOf` |  |
+
+## `SessionTokenUsageResponse`
+
+**Type:** `object`
+
+**Description:** Defines the response for retrieving a session's token usage.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token_count*` | `integer` |  |
+| `token_limit*` | `integer` |  |
+| `percentage*` | `number` |  |
+
+## `SessionUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `anyOf` |  |
+| `provider_name` | `anyOf` |  |
+| `stt_provider_name` | `anyOf` |  |
+| `tts_provider_name` | `anyOf` |  |
+
+## `SkillConfig`
+
+**Type:** `object`
+
+**Description:** Per-skill enable/disable with optional config.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` |  |
+| `cwd_jail` | `anyOf` |  |
+| `max_file_size_mb` | `anyOf` |  |
+| `sandbox` | `anyOf` |  |
+
+## `SkillCreate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name*` | `string` |  |
+| `description` | `anyOf` |  |
+| `skill_type` | `string` |  |
+| `config` | `object` |  |
+| `system_prompt` | `anyOf` |  |
+| `is_enabled` | `boolean` |  |
+| `features` | `array` |  |
+| `is_system` | `boolean` |  |
+| `extra_metadata` | `object` |  |
+| `preview_markdown` | `anyOf` |  |
+
+## `SkillResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name*` | `string` |  |
+| `description` | `anyOf` |  |
+| `skill_type` | `string` |  |
+| `config` | `object` |  |
+| `system_prompt` | `anyOf` |  |
+| `is_enabled` | `boolean` |  |
+| `features` | `array` |  |
+| `is_system` | `boolean` |  |
+| `extra_metadata` | `object` |  |
+| `preview_markdown` | `anyOf` |  |
+| `id*` | `integer` |  |
+| `owner_id*` | `string` |  |
+| `created_at*` | `string` |  |
+
+## `SkillUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `anyOf` |  |
+| `description` | `anyOf` |  |
+| `skill_type` | `anyOf` |  |
+| `config` | `anyOf` |  |
+| `system_prompt` | `anyOf` |  |
+| `is_enabled` | `anyOf` |  |
+| `features` | `anyOf` |  |
+| `is_system` | `anyOf` |  |
+| `extra_metadata` | `anyOf` |  |
+| `preview_markdown` | `anyOf` |  |
+
+## `SpeechRequest`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `text*` | `string` |  |
+
+## `SwarmConfigUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `external_endpoint` | `anyOf` |  |
+
+## `SystemStatus`
+
+**Type:** `object`
+
+**Description:** Schema for overall system status, including TLS and OIDC state.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `status*` | `string` |  |
+| `oidc_enabled*` | `boolean` |  |
+| `tls_enabled*` | `boolean` |  |
+| `external_endpoint` | `anyOf` |  |
+| `version*` | `string` |  |
+
+## `UserGroupUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `group_id*` | `string` |  |
+
+## `UserNodePreferences`
+
+**Type:** `object`
+
+**Description:** Stored in User.preferences['nodes'].
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `default_node_ids` | `array` | Node IDs auto-attached when starting a new session |
+| `data_source` | `Ref: NodeDataSourceConfig` |  |
+
+## `UserPreferences`
+
+**Type:** `object`
+
+**Description:** Schema for user-specific LLM, TTS, STT preferences.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `llm` | `object` |  |
+| `tts` | `object` |  |
+| `stt` | `object` |  |
+| `statuses` | `anyOf` |  |
+
+## `UserProfile`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id*` | `string` |  |
+| `email*` | `string` |  |
+| `username` | `anyOf` |  |
+| `full_name` | `anyOf` |  |
+| `role` | `string` |  |
+| `group_id` | `anyOf` |  |
+| `group_name` | `anyOf` |  |
+| `avatar_url` | `anyOf` |  |
+| `created_at*` | `string` |  |
+| `last_login_at` | `anyOf` |  |
+
+## `UserProfileUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `username` | `anyOf` |  |
+| `full_name` | `anyOf` |  |
+| `avatar_url` | `anyOf` |  |
+
+## `UserRoleUpdate`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `role*` | `string` |  |
+
+## `UserStatus`
+
+**Type:** `object`
+
+**Description:** Schema for the response when checking a user's status.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id*` | `string` | The internal user ID. |
+| `email` | `anyOf` | The user's email address. |
+| `is_logged_in` | `boolean` | Indicates if the user is currently authenticated. |
+| `is_anonymous` | `boolean` | Indicates if the user is an anonymous user. |
+| `oidc_configured` | `boolean` | Whether OIDC SSO is enabled on the server. |
+| `allow_password_login` | `boolean` | Whether local password login is supported by the server. |
+
+## `ValidationError`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `loc*` | `array` |  |
+| `msg*` | `string` |  |
+| `type*` | `string` |  |
+| `input` | `` |  |
+| `ctx` | `object` |  |
+
+## `VerifyProviderRequest`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `provider_name*` | `string` |  |
+| `provider_type` | `anyOf` |  |
+| `api_key` | `anyOf` |  |
+| `model` | `anyOf` |  |
+| `voice` | `anyOf` |  |
+
+## `VerifyProviderResponse`
+
+**Type:** `object`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `success*` | `boolean` |  |
+| `message*` | `string` |  |
+
diff --git a/ai-hub/docs/api_reference/sessions.md b/ai-hub/docs/api_reference/sessions.md
new file mode 100644
index 0000000..1155d9c
--- /dev/null
+++ b/ai-hub/docs/api_reference/sessions.md
@@ -0,0 +1,512 @@
+# API Reference: Sessions
+
+## POST `/sessions/`
+
+**Summary:** Create a New Chat Session
+
+**Description:** Create a New Chat Session
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SessionCreate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/sessions/' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/sessions/`
+
+**Summary:** Get All Chat Sessions
+
+**Description:** Get All Chat Sessions
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `user_id` | query | Yes | string |  |
+| `feature_name` | query | No | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/sessions/?user_id=<user_id>&feature_name=<feature_name>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## DELETE `/sessions/`
+
+**Summary:** Delete All Sessions for Feature
+
+**Description:** Delete All Sessions for Feature
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `user_id` | query | Yes | string |  |
+| `feature_name` | query | No | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/sessions/?user_id=<user_id>&feature_name=<feature_name>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/sessions/{session_id}/chat`
+
+**Summary:** Send a Message in a Session (Streaming)
+
+**Description:** Streams AI response using Server-Sent Events (SSE).
+Yields tokens, reasoning, and tool executions in real-time.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `ChatRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/chat' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/sessions/{session_id}/messages`
+
+**Summary:** Get Session Chat History
+
+**Description:** Get Session Chat History
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/messages' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/sessions/{session_id}/clear-history`
+
+**Summary:** Clear Chat History (Preserve Session)
+
+**Description:** Deletes all messages for a session but preserves the session itself
+(node attachments, workspace ID, sync config, title all remain intact).
+Useful in Swarm Control to start a fresh chat without losing the file sync workspace.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/clear-history' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/sessions/{session_id}/tokens`
+
+**Summary:** Get Session Token Usage
+
+**Description:** Get Session Token Usage
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/tokens' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/sessions/{session_id}`
+
+**Summary:** Get a Single Session
+
+**Description:** Get a Single Session
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/sessions/{session_id}' \
+  -H 'accept: application/json'
+```
+
+---
+
+## PATCH `/sessions/{session_id}`
+
+**Summary:** Update a Chat Session
+
+**Description:** Update a Chat Session
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SessionUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PATCH' \
+  'http://localhost:8000/api/v1/sessions/{session_id}' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## DELETE `/sessions/{session_id}`
+
+**Summary:** Delete a Chat Session
+
+**Description:** Delete a Chat Session
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/sessions/{session_id}' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/sessions/messages/{message_id}/audio`
+
+**Summary:** Upload audio for a specific message
+
+**Description:** Upload audio for a specific message
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `message_id` | path | Yes | integer |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `multipart/form-data`
+- **Schema:** `Body_upload_message_audio_sessions_messages__message_id__audio_post` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/sessions/messages/{message_id}/audio' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: multipart/form-data' \
+  -F 'file=@/path/to/file'
+```
+
+---
+
+## GET `/sessions/messages/{message_id}/audio`
+
+**Summary:** Get audio for a specific message
+
+**Description:** Get audio for a specific message
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `message_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/sessions/messages/{message_id}/audio' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/sessions/{session_id}/nodes`
+
+**Summary:** Attach Nodes to Session
+
+**Description:** Attach one or more Agent Nodes to a chat session.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `NodeAttachRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/nodes' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/sessions/{session_id}/nodes`
+
+**Summary:** Get Session Node Status
+
+**Description:** Returns all nodes attached to a session and their current sync status.
+Merges persisted sync_status with live connection state from the registry.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/nodes' \
+  -H 'accept: application/json'
+```
+
+---
+
+## DELETE `/sessions/{session_id}/nodes/{node_id}`
+
+**Summary:** Detach Node from Session
+
+**Description:** Detach Node from Session
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+| `node_id` | path | Yes | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/nodes/{node_id}' \
+  -H 'accept: application/json'
+```
+
+---
+
+## POST `/sessions/{session_id}/cancel`
+
+**Summary:** Cancel Running AI Task
+
+**Description:** Cancel Running AI Task
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `session_id` | path | Yes | integer |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/sessions/{session_id}/cancel' \
+  -H 'accept: application/json'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/skills.md b/ai-hub/docs/api_reference/skills.md
new file mode 100644
index 0000000..9b38855
--- /dev/null
+++ b/ai-hub/docs/api_reference/skills.md
@@ -0,0 +1,143 @@
+# API Reference: Skills
+
+## GET `/skills/`
+
+**Summary:** List Skills
+
+**Description:** List all skills accessible to the user.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `feature` | query | No | anyOf | Filter skills by feature (e.g., 'chat', 'voice') |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/skills/?feature=<feature>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/skills/`
+
+**Summary:** Create Skill
+
+**Description:** Create a new skill.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SkillCreate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/skills/' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## PUT `/skills/{skill_id}`
+
+**Summary:** Update Skill
+
+**Description:** Update an existing skill. User must be admin or the owner.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `skill_id` | path | Yes | integer |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SkillUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/skills/{skill_id}' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## DELETE `/skills/{skill_id}`
+
+**Summary:** Delete Skill
+
+**Description:** Delete a skill.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `skill_id` | path | Yes | integer |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/skills/{skill_id}' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/stt.md b/ai-hub/docs/api_reference/stt.md
new file mode 100644
index 0000000..85af7b8
--- /dev/null
+++ b/ai-hub/docs/api_reference/stt.md
@@ -0,0 +1,45 @@
+# API Reference: STT
+
+## POST `/stt/transcribe`
+
+**Summary:** Transcribe audio to text
+
+**Description:** Transcribes an uploaded audio file into text using the configured STT service.
+
+The audio file is expected to be a common audio format like WAV or MP3,
+though the specific provider implementation will determine supported formats.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `provider_name` | query | No | anyOf |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `multipart/form-data`
+- **Schema:** `Body_transcribe_audio_to_text_stt_transcribe_post` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | The transcribed text from the audio file. |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/stt/transcribe?provider_name=<provider_name>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: multipart/form-data' \
+  -F 'file=@/path/to/file'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/tts.md b/ai-hub/docs/api_reference/tts.md
new file mode 100644
index 0000000..d223116
--- /dev/null
+++ b/ai-hub/docs/api_reference/tts.md
@@ -0,0 +1,76 @@
+# API Reference: TTS
+
+## POST `/speech`
+
+**Summary:** Generate speech from text
+
+**Description:** Generate speech from text
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `stream` | query | No | boolean | If true, returns a streamed audio response. Otherwise, returns a complete file. |
+| `as_wav` | query | No | boolean | If true, returns WAV format audio. If false, returns raw PCM audio data. Only applies when stream is true. |
+| `provider_name` | query | No | string | Optional session-level override for the TTS provider |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `SpeechRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Audio bytes in WAV or PCM format, either as a complete file or a stream. |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/speech?stream=<stream>&as_wav=<as_wav>&provider_name=<provider_name>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/speech/voices`
+
+**Summary:** List available TTS voices
+
+**Description:** List available TTS voices
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `provider` | query | No | string | Optional provider name |
+| `api_key` | query | No | string | Optional API key override |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | A list of voice names |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/speech/voices?provider=<provider>&api_key=<api_key>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
diff --git a/ai-hub/docs/api_reference/users.md b/ai-hub/docs/api_reference/users.md
new file mode 100644
index 0000000..deb8d8d
--- /dev/null
+++ b/ai-hub/docs/api_reference/users.md
@@ -0,0 +1,821 @@
+# API Reference: Users
+
+## GET `/users/login`
+
+**Summary:** Initiate OIDC Login Flow
+
+**Description:** Initiates the OIDC authentication flow.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `frontend_callback_uri` | query | No | anyOf | The frontend URI to redirect back to after OIDC provider. |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/login?frontend_callback_uri=<frontend_callback_uri>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/users/login/callback`
+
+**Summary:** Handle OIDC Login Callback
+
+**Description:** Handles the callback from the OIDC provider.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `code` | query | Yes | string | Authorization code from OIDC provider |
+| `state` | query | Yes | string | The original frontend redirect URI |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/login/callback?code=<code>&state=<state>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/users/me`
+
+**Summary:** Get Current User Status
+
+**Description:** Checks the login status of the current user.
+Requires a valid user_id to be present in the request header.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/me' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/users/login/local`
+
+**Summary:** Local Authentication Fallback
+
+**Description:** Day 1: Local Username/Password Login.
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `LocalLoginRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/login/local' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## PUT `/users/password`
+
+**Summary:** Update User Password
+
+**Description:** Update User Password
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `PasswordUpdateRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/users/password' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/users/me/profile`
+
+**Summary:** Get Current User Profile
+
+**Description:** Retrieves profile information for the current user.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/me/profile' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## PUT `/users/me/profile`
+
+**Summary:** Update User Profile
+
+**Description:** Updates profile details for the current user.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `UserProfileUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/users/me/profile' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/users/me/config`
+
+**Summary:** Get Current User Preferences
+
+**Description:** Gets user specific preferences (LLM, TTS, STT config overrides).
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/me/config' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## PUT `/users/me/config`
+
+**Summary:** Update Current User Preferences
+
+**Description:** Updates user specific preferences.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `UserPreferences` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/users/me/config' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/users/me/config/models`
+
+**Summary:** Get Models for Provider
+
+**Description:** Get Models for Provider
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `provider_name` | query | Yes | string |  |
+| `section` | query | No | string |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/me/config/models?provider_name=<provider_name>&section=<section>' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/users/me/config/providers`
+
+**Summary:** Get All Valid Providers per Section
+
+**Description:** Get All Valid Providers per Section
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `section` | query | No | string |  |
+| `configured_only` | query | No | boolean | If true, only returns providers currently configured in preferences or system defaults |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/me/config/providers?section=<section>&configured_only=<configured_only>' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/users/me/config/verify_llm`
+
+**Summary:** Verify Llm
+
+**Description:** Verify Llm
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `VerifyProviderRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/me/config/verify_llm' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## POST `/users/me/config/verify_tts`
+
+**Summary:** Verify Tts
+
+**Description:** Verify Tts
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `VerifyProviderRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/me/config/verify_tts' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## POST `/users/me/config/verify_stt`
+
+**Summary:** Verify Stt
+
+**Description:** Verify Stt
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `VerifyProviderRequest` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/me/config/verify_stt' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## POST `/users/logout`
+
+**Summary:** Log Out the Current User
+
+**Description:** Simulates a user logout. In a real application, this would clear the session token or cookie.
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/logout' \
+  -H 'accept: application/json'
+```
+
+---
+
+## GET `/users/me/config/export`
+
+**Summary:** Export Configurations to YAML
+
+**Description:** Exports the effective user configuration as a YAML file (Admin only).
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/me/config/export' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/users/me/config/import`
+
+**Summary:** Import Configurations from YAML
+
+**Description:** Imports user configuration from a YAML file.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `multipart/form-data`
+- **Schema:** `Body_import_user_config_yaml_users_me_config_import_post` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/me/config/import' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: multipart/form-data' \
+  -F 'file=@/path/to/file'
+```
+
+---
+
+## GET `/users/admin/users`
+
+**Summary:** List All Users (Admin Only)
+
+**Description:** Returns a list of all registered users in the system.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/admin/users' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## PUT `/users/admin/users/{uid}/role`
+
+**Summary:** Update User Role (Admin Only)
+
+**Description:** Updates a user's role. Prevents demoting the last administrator.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `uid` | path | Yes | string |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `UserRoleUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/users/admin/users/{uid}/role' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## PUT `/users/admin/users/{uid}/group`
+
+**Summary:** Update User Group (Admin Only)
+
+**Description:** Assigns a user to a group.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `uid` | path | Yes | string |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `UserGroupUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/users/admin/users/{uid}/group' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## GET `/users/admin/groups`
+
+**Summary:** List All Groups (Admin Only)
+
+**Description:** Returns all existing groups.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'GET' \
+  'http://localhost:8000/api/v1/users/admin/groups' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+
+## POST `/users/admin/groups`
+
+**Summary:** Create Group (Admin Only)
+
+**Description:** Creates a new group.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `GroupCreate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/api/v1/users/admin/groups' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## PUT `/users/admin/groups/{gid}`
+
+**Summary:** Update Group (Admin Only)
+
+**Description:** Updates a group's metadata or policy.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `gid` | path | Yes | string |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Request Body
+
+**Required:** Yes
+
+- **Media Type:** `application/json`
+- **Schema:** `GroupUpdate` (Define in Models)
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'PUT' \
+  'http://localhost:8000/api/v1/users/admin/groups/{gid}' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+---
+
+## DELETE `/users/admin/groups/{gid}`
+
+**Summary:** Delete Group (Admin Only)
+
+**Description:** Deletes a group. Users are moved back to 'ungrouped'.
+
+#### Parameters
+
+| Name | In | Required | Type | Description |
+|------|----|----------|------|-------------|
+| `gid` | path | Yes | string |  |
+| `x-user-id` | header | No | anyOf |  |
+
+#### Responses
+
+| Status Code | Description |
+|-------------|-------------|
+| `200` | Successful Response |
+| `422` | Validation Error |
+
+#### Example Usage
+
+```bash
+curl -X 'DELETE' \
+  'http://localhost:8000/api/v1/users/admin/groups/{gid}' \
+  -H 'accept: application/json' \
+  -H 'X-User-ID: <your_user_id>'
+```
+
+---
+