diff --git a/README.md b/README.md
index 4b1de6a3..ff525969 100644
--- a/README.md
+++ b/README.md
@@ -89,7 +89,7 @@ export VITE_ATM_SIMU=http://[Service url]:[Service port]
 cd config/dev/cab-standalone
 ./docker-compose.sh
 ```
-> **_NOTE:_** You will see the word cab (Cockpit Assistant Bidirectionnel) on most files in the project. Note that it was the initial project name of InteractiveAI. Might be updated later. 
+> **_NOTE:_** You will see the word cab on most files in the project. Note that it was the initial project name of InteractiveAI. Might be updated later. 
 
 3. **Setting up Keycloak `Frontend URL`**  
     * Access Keycloak Interface: 
@@ -99,13 +99,13 @@ cd config/dev/cab-standalone
       - Log in to the Keycloak admin console using your administrator credentials (`admin:admin` by default)
     * Configure frontendUrl:
       - On the Keycloak admin console, locate and click on the "Realm Settings" section.
-      - In the Frontend URL setting, add the URL of your Assistant Platform frontend as a valid redirect URI. This URL is typically where your frontend application is hosted. For example, if your frontend is hosted locally for development purposes, you might add `http://localhost:3200/*`.
-      - After adding the frontend URL, save the changes to update the client settings.
+      - In the Frontend URL field, add the URL of InteractiveAI frontend. If your frontend is hosted locally for development purposes, you might add `http://localhost:3200/`.
+      - After adding the frontend URL, save the changes.
     * Configure Valid Redirect URIs:
       - On the Keycloak admin console, locate and click on the "Clients" section.
-      - Select the client representing your Assistant Platform application.  
-      - Within the client settings, look for the "Valid Redirect URIs" or similar configuration field.
-      - Add the URL of your Assistant Platform frontend, it should match the one used in the frontendUrl setting.
+      - Select the client (opfab-client).  
+      - Within the client settings, look for the "Valid Redirect URIs" field.
+      - Add the URL of the frontend with /*, if it's local deployment: `http://localhost:3200/*`.
       - After adding the Valid Redirect URIs, save the changes to update the client settings.
 
 
@@ -121,7 +121,7 @@ cd resources
 ./loadTestConf.sh
 ```
 
-5. If you encounter CORS errors (which can happen if you start tha platform in a non-HTTPS environment), you can start your browser with security mode disabled.
+5. If you encounter CORS errors (which can happen if you start the platform in a non-HTTPS environment), you can start your browser with security mode disabled.
 
 ```sh
 your-chromium-browser --disable-web-security --user-data-dir="[some directory here]" # replace your-chromium-browser with your browser
@@ -131,7 +131,7 @@ your-chromium-browser --disable-web-security --user-data-dir="[some directory he
 
 ### Default ports
 
-This project is based on a microservice architecture. Every service run on a specific port. Some of th default ports are as fellow:
+This project is based on a microservice architecture. Every service run on a specific port. Some of the default ports are as fellow:
 * Frontend: 3200
 * Context Service: 5100
 * Event Service: 5000
diff --git a/docs/AIAgent_integration.md b/docs/AIAgent_integration.md
new file mode 100644
index 00000000..dafd9de7
--- /dev/null
+++ b/docs/AIAgent_integration.md
@@ -0,0 +1,180 @@
+# AI Agent Integration
+
+## Overview
+
+InteractiveAI is a platform that bridges AI agents with digital environments (simulators) through a web interface. It provides operators with real-time event monitoring, contextual recommendations, and the ability to apply AI-generated actions directly to their environment.
+
+This documentation uses the PowerGrid domain as an example to illustrate how to integrate an AI agent (ExpertRL Agent) with InteractiveAI.
+
+In our enviroment diagram, we are refering to steps 3 and 4.
+
+![Architecture diagram](img/InteractiveAI_AIAgent.png)
+*Figure 1: InteractiveAI general workflow*
+
+---
+
+## AI Agent Repository Structure
+
+The agent repository should include an `app` folder and a `Dockerfile` at the root. The following structure is used by ExpertAgent ([reference implementation](https://github.com/ainetus/T2.1_deep_expert/tree/docker)):
+
+```
+agent-repo/
+├── Dockerfile
+├── requirements_docker.txt
+├── setup.py
+└── app/
+    ├── __init__.py       # Runs the API
+    └── main.py           # FastAPI app definition
+```
+
+### `Dockerfile` (minimal illustration)
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install git
+# Create a directory for environment
+
+# Install Agent package dependencies
+COPY requirements_docker.txt .
+RUN pip install --no-cache-dir -r requirements_docker.txt
+
+# Copy API + agent package
+COPY app ./app/
+
+# Install the project using setup.py at the root
+RUN pip install .
+
+# Expose port
+EXPOSE 8000
+
+# Run server
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+### `app/main.py`
+
+```python
+from fastapi import FastAPI
+
+agent = ExpertAgentRL(kwargs)
+app = FastAPI()
+
+@app.post("/api/v1/recommendation")
+def get_recommendation(request: RecommendationRequest):
+    # Convert incoming data to the observation format your agent expects
+    observation = {
+        "event": request.event,
+        "context": request.context,
+    }
+    # Get recommendation from RL agent
+    obs.from_json(observation.get("context", {}).get("observation"))
+    action = agent.act(obs, reward=None, done=False)
+    result = get_parade_info(action, obs)
+    if result is not list:
+        result = [result]
+    return result
+```
+
+For a complete implementation of `main.py`, see [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/app/main.py).  
+The transformation of an action to the required format is handled by `get_parade_info(act, obs)`, available [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/app/main.py#L100).
+
+---
+
+## Running and Testing the Agent Locally
+
+### 1. Build the Docker image
+
+```bash
+docker build -t expert-agent-api .
+```
+
+### 2. Run the container
+
+```bash
+docker run -p 8000:8000 expert-agent-api
+```
+
+### 3. Test the recommendation endpoint
+
+Send a POST request using a context JSON file:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/recommendation \
+  -H "Content-Type: application/json" \
+  --data @rte_recommendation.json
+```
+
+The `rte_recommendation.json` context example is available [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/app/rte_recommendation.json). The expected output is a list of recommendations in dictionary format:
+
+```json
+[
+  {
+    "title": "Topological recommendation: Schematic acquisition at substation 11",
+    "description": "Assign bus 1 to line (extremity) id 11, Assign bus 1 to line (origin) id 13, Assign bus 1 to load id 12",
+    "use_case": "PowerGrid",
+    "agent_type": 2,
+    "actions": [
+      {
+        "_set_line_status": [0, 0, 0, "..."],
+        "_switch_line_status": [false, false, "..."],
+        "_set_topo_vect": [0, 0, 1, 1, 1, "..."],
+        "_change_bus_vect": [false, false, "..."],
+        "_redispatch": [0.0, 0.0, "..."],
+        "_storage_power": [],
+        "_curtail": [-1.0, -1.0, "..."],
+        "_raise_alarm": [false, false, false],
+        "_raise_alert": []
+      }
+    ],
+    "kpis": {
+      "type_of_the_reco": "Topological",
+      "efficiency_of_the_reco": 0.8976841568946838
+    }
+  }
+]
+```
+
+> A helper function `get_parade_info(act, obs)` is provided — it takes an action and the corresponding observation and outputs this dictionary format per action.
+
+---
+
+## Complete Dockerfile
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install git
+RUN apt-get update && apt-get install -y git && apt-get clean
+
+# Create a directory for environment
+RUN mkdir -p /home/root/data_grid2op/
+RUN git clone https://github.com/AI4REALNET/grid2op-scenario.git /tmp/grid2op-scenario
+RUN mkdir -p /root/data_grid2op
+RUN cp -r /tmp/grid2op-scenario/ai4realnet_small /root/data_grid2op/ai4realnet_small
+RUN rm -rf /tmp/grid2op-scenario
+
+# Python dependencies
+COPY requirements_docker.txt .
+RUN pip install --no-cache-dir -r requirements_docker.txt
+
+# Copy API + agent package
+COPY app ./app/
+COPY ExpertAgent ./ExpertAgent/
+COPY setup.py .
+
+# Install the project using setup.py at the root
+RUN pip install .
+
+# Expose port
+EXPOSE 8000
+
+# Run server
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+For the full Dockerfile example, see [here](https://github.com/ainetus/T2.1_deep_expert/blob/docker/Dockerfile).
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..82c14d80
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,36 @@
+# InteractiveAI
+
+InteractiveAI is an open-source platform for monitoring and managing complex industrial networks. It integrates human-machine interaction and human expertise to optimize AI performance in demanding operational environments.
+
+## Documentation
+
+- [Platform Overview](./overview.md) — Architecture, services, and integration model
+- [Getting Started](./getting-started.md) — How to connect your system to the platform
+
+### API Reference
+
+| Service | Description |
+|---|---|
+| [Event Service](./api/event-service.md) | Push events into the platform |
+| [Context Service](./api/context-service.md) | Push context updates to the platform |
+| [Historic Service](./api/historic-service.md) | Event and action log; report generation |
+| [Recommendation Service](./api/recommendation-service.md) | AI and ontology-based recommendations |
+| [Capitalization Service](./api/capitalization-service.md) | Operator feedback storage |
+
+## Quick start
+
+External systems only need to call two APIs:
+
+```http
+# 1. Send an event
+POST http://{Platform_Server}/cab_event/api/v1/events
+
+# 2. Send a context update
+POST http://{Platform_Server}/cab_context/api/v1/contexts
+```
+
+See [Getting Started](./getting-started.md) for full details, including the simulator callback endpoint you need to implement.
+
+## Source
+
+Based on the [IRT-SystemX/InteractiveAI](https://github.com/ainetus/InteractiveAI) platform.
diff --git a/docs/api/authentication.md b/docs/api/authentication.md
new file mode 100644
index 00000000..31358dda
--- /dev/null
+++ b/docs/api/authentication.md
@@ -0,0 +1,103 @@
+# Authentication
+
+All InteractiveAI APIs require a bearer token. You must obtain a token before calling any endpoint, and include it in every request.
+
+## Get a token
+
+```http
+POST http://{Platform_Server}:3200/auth/token
+Content-Type: application/x-www-form-urlencoded
+```
+
+### Request body
+
+| Field | Value |
+|---|---|
+| `username` | `publisher_test`
+| `password` |`test` |
+| `grant_type` | `password` |
+| `clientId` | `opfab-client` |
+
+### Example (curl)
+
+```bash
+curl -X POST http://{Platform_Server}:3200/auth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=publisher_test&password=test&grant_type=password&clientId=opfab-client"
+```
+
+### Response
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  ...
+}
+```
+
+The token to use in subsequent requests is: `{token_type} {access_token}` (e.g. `Bearer eyJ...`).
+
+---
+
+## Use the token
+
+Include the token in the `Authorization` header of every API call:
+
+```http
+POST http://{Platform_Server}:3200/cab_event/api/v1/events
+Authorization: Bearer eyJ...
+Content-Type: application/json
+```
+
+---
+
+## Python example
+
+```python
+import requests
+import json
+
+server_url = "{Platform_Server}"
+username = "publisher_test"
+password = "test"
+client_id = "opfab-client"
+
+token_url = f"http://{server_url}:3200/auth/token"
+
+# Request token
+response = requests.post(
+    token_url,
+    headers={"Content-Type": "application/x-www-form-urlencoded"},
+    data=f"username={username}&password={password}&grant_type=password&clientId={client_id}"
+)
+
+if response.status_code >= 500:
+    raise ValueError(f"Token request failed with status code {response.status_code}")
+
+data = response.json()
+token = data["token_type"] + " " + data["access_token"]
+
+# Use the token in subsequent requests
+headers = {
+    "Authorization": token,
+    "Content-Type": "application/json"
+}
+
+# Example: send an event
+requests.post(
+    f"http://{server_url}:3200/cab_event/api/v1/events",
+    headers=headers,
+    json={ ... }
+)
+```
+
+---
+
+## API base URLs
+
+| Service | URL |
+|---|---|
+| Auth | `http://{Platform_Server}:3200/auth/token` |
+| Event | `http://{Platform_Server}:3200/cab_event/api/v1/events` |
+| Context | `http://{Platform_Server}:3200/cabcontext/api/v1/contexts` |
diff --git a/docs/api/capitalization-service.md b/docs/api/capitalization-service.md
new file mode 100644
index 00000000..a52fe949
--- /dev/null
+++ b/docs/api/capitalization-service.md
@@ -0,0 +1,51 @@
+# Capitalization Service API
+
+The Capitalization Service stores operator feedback on recommendations — whether a recommendation was accepted or rejected. This data is used to improve AI models over time.
+
+This API is called automatically by the HMI module when the operator makes a decision. It is documented here for reference.
+
+**Base path:** `/cab_capitalization/api/v1`
+
+---
+
+## Store feedback
+
+```http
+POST http://{Platform_Server}/cab_capitalization/api/v1/feedbacks
+Content-Type: application/json
+```
+
+### Feedback object
+
+| Field | Type | Description |
+|---|---|---|
+| `event_id` | string | ID of the event that triggered the recommendation request |
+| `context_id` | string | ID of the context at the time of the decision |
+| `date` | datetime | Timestamp of the feedback (ISO 8601) |
+| `feedback` | boolean | `true` if the recommendation was chosen, `false` if rejected |
+| `recommendation` | object | The full recommendation object that was accepted or rejected |
+
+### Example
+
+```json
+{
+  "event_id": "evt_00312",
+  "context_id": "ctx_00178",
+  "date": "2024-03-15T10:31:00Z",
+  "feedback": true,
+  "recommendation": {
+    "title": "Reroute traffic via L45",
+    "description": "Redirect load from L42 to L45.",
+    "agent_type": "AI",
+    "actions": [
+      { "type": "reroute", "line_from": "L42", "line_to": "L45", "load_percent": 70 }
+    ]
+  }
+}
+```
+
+---
+
+## Postman collection
+
+[Capitalisation-service.postman_collection.json](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Capitalisation-service.postman_collection.json)
diff --git a/docs/api/context-service.md b/docs/api/context-service.md
new file mode 100644
index 00000000..f39113e4
--- /dev/null
+++ b/docs/api/context-service.md
@@ -0,0 +1,97 @@
+# Context Service API
+
+The Context Service collects and analyzes data related to the current operating environment: external conditions, controlled-system state, operator cognitive load, and mission parameters. The HMI module polls it continuously to display real-time context to the operator.
+
+**Base path:** `/cab_context/api/v1`
+
+> **Authentication required** — All requests must include a bearer token in the `Authorization` header. See [Authentication](./authentication.md) for how to obtain one.
+---
+
+## Send a context update
+
+```http
+POST http://{Platform_Server}/cab_context/api/v1/contexts
+Content-Type: application/json
+```
+
+### Generic payload
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `use_case` | string | ✅ | Identifier for the application domain / use case |
+| `date` | datetime | ✅ | Timestamp of the context snapshot (ISO 8601) |
+| `data` | object | ❌ | Use-case-specific context information (see below) |
+
+### Use-case-specific data (`data` field)
+
+As with events, the `data` field carries domain-specific context that the HMI uses to render its context view.
+
+**Example — Power grid use case:**
+```json
+{
+  "use_case": "Powergrid",
+  "date": "2024-03-15T10:23:00Z",
+  "data": {
+    "grid_load_percent": 87.3,
+    "weather": "storm",
+    "operator_shift": "night",
+    "active_incidents": 2
+  }
+}
+```
+
+**Example — Railway use case:**
+```json
+{
+  "use_case": "Railway",
+  "date": "2024-03-15T10:00:00",
+  "data": {
+    "trains": [
+      {
+        "id_train": "AB001",
+        "nb_passengers_onboard": "459",
+        "trip": "Paris/Bordeaux",
+        "stops": "Angoulême/Bordeaux",
+        "failure": false
+      }
+    ]
+  }
+}
+```
+> The `trains` array accepts multiple train objects. Optional fields include `nb_passengers_connection`, `latitude`, `longitude`, and `speed` — omit them if not available.
+
+**Example — ATM use case:**
+```json
+{
+  "use_case": "ATM",
+  "date": "2024-03-15T10:00:00",
+  "data": {
+    "ApDest": "LFBO",
+    "Current_airspeed": 450,
+    "Latitude": 43.6295,
+    "Longitude": 1.3637,
+    "wpList": ["TOU", "LESDO", "LFBO"]
+  }
+}
+```
+
+> `wpList` is the list of remaining waypoints for the aircraft. `ApDest` is the destination airport (ICAO code).
+---
+
+## Retrieve current context
+
+Called by the HMI module to get the context at a given point in time. The platform automatically filters results to the running use case of the connected operator.
+
+```http
+GET http://{Platform_Server}/cab_context/api/v1/contexts/{date}
+```
+
+| Parameter | Location | Description |
+|---|---|---|
+| `date` | Path | ISO 8601 timestamp — returns the context closest to this date |
+
+---
+
+## Postman collection
+
+[Context-service.postman_collection.json](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Context-service.postman_collection.json)
diff --git a/docs/api/event-service.md b/docs/api/event-service.md
new file mode 100644
index 00000000..b1fce0bc
--- /dev/null
+++ b/docs/api/event-service.md
@@ -0,0 +1,95 @@
+# Event Service API
+
+The Event Service receives incoming messages, categorizes them, prioritizes tasks, and forwards notifications to the HMI frontend. It also maintains the system timeline.
+
+**Base path:** `/cab_event/api/v1`
+
+> **Authentication required** — All requests must include a bearer token in the `Authorization` header. See [Authentication](./authentication.md) for how to obtain one.
+---
+
+## Send an event
+
+```http
+POST http://{Platform_Server}/cab_event/api/v1/events
+Content-Type: application/json
+```
+
+### Generic payload
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `use_case` | string | ✅ | Identifier for the application domain / use case (PowerGrid, Railway, ATM) |
+| `title` | string | ✅ | Short title of the event |
+| `description` | string | ✅ | Human-readable description of the event |
+| `criticality` | string/int | ✅ | Severity level of the event (HIGH, MEDIUM, LOW) |
+| `start_date` | datetime | ✅ | When the event started (ISO 8601) |
+| `end_date` | datetime | ❌ | When the event ended — omit if unknown |
+| `parent_event_id` | string | ❌ | ID of the parent event, if this event is a consequence of another |
+| `data` | object | ❌ | Use-case-specific payload (see below) |
+
+### Use-case-specific data (`data` field)
+
+The `data` field is a free-form object used to pass domain-specific information. This data can be consumed by use-case-specific HMI components.
+
+**Example — Power grid use case:**
+```json
+{
+  "use_case": "power_grid",
+  "title": "Line overload detected",
+  "description": "Transmission line L42 is operating above rated capacity.",
+  "criticality": "HIGH",
+  "start_date": "2024-03-15T10:23:00Z",
+  "data": {
+    "line_id": "L42",
+    "load_percentage": 112.5,
+    "substation": "SUB-07"
+  }
+}
+```
+
+**Example — Railway  use case:**
+```json
+{
+  "use_case": "Railway",
+  "criticality": "HIGH",
+  "title": "Passenger taken ill in Poitiers",
+  "description": "Passenger taken ill in TGV AB001. Emergency services intervention in the Poitiers station. Impossible to access the Poitiers station. Estimated time of service traffic resumption: 12:00.",
+  "start_date": "2024-03-15T10:00:00",
+  "end_date": "2024-03-15T12:00:00",
+  "data": {
+    "id_event": "1",
+    "event_type": "PASSENGER",
+    "id_train": "AB001",
+    "agent_id": "1",
+    "delay": 0
+  }
+}
+```
+> `event_type` can be `PASSENGER`, `INFRASTRUCTURE`, `IMPACT`, or `HARDWARE`.
+> 
+**Example — ATM use case:**
+```json
+{
+  "use_case": "ATM",
+  "criticality": "HIGH",
+  "title": "Plane in unauthorized sector",
+  "description": "Aircraft AF1234 has entered sector TMA-NW without clearance. The aircraft is currently at FL320, deviating from its assigned route. Immediate coordination required with adjacent sector control.",
+  "start_date": "2024-03-15T10:00:00",
+  "end_date": "2024-03-15T10:30:00",
+  "data": {
+    "system": "none",
+    "event_type": "sectorization",
+    "id_plane": "1"
+  }
+}
+```
+
+### Response
+
+On success, the API returns the created event object including its generated `id`.
+
+---
+
+## Postman collection
+
+[Event-service.postman_collection.json](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Event-service.postman_collection.json)
diff --git a/docs/api/historic-service.md b/docs/api/historic-service.md
new file mode 100644
index 00000000..aac0e1d6
--- /dev/null
+++ b/docs/api/historic-service.md
@@ -0,0 +1,64 @@
+# Historic Service API
+
+The Historic Service maintains a log of all events and operator actions. It is called automatically by the Event Service and the HMI module — external integrators generally do not need to call it directly. It is documented here for reference and for generating reports.
+
+**Base path:** `/api/v1`
+
+---
+
+## Write a trace
+
+```http
+POST http://{Platform_Server}/api/v1/traces
+Content-Type: application/json
+```
+
+### Payload
+
+| Field | Type | Description |
+|---|---|---|
+| `trace_type` | string | Type of trace (see values below) |
+| `data` | object | Data associated with the trace |
+
+### Trace types
+
+| `trace_type` | Triggered when |
+|---|---|
+| `EVENT` | An event is received by the platform |
+| `ASKFORHELP` | The operator requests assistance from the AI assistant |
+| `ACTION` | The operator resolves the problem independently (without AI help) |
+| `AWARD` | The operator selects one of the AI recommendations |
+
+### Example
+
+```json
+{
+  "trace_type": "AWARD",
+  "data": {
+    "event_id": "evt_00312",
+    "recommendation_id": "rec_00089",
+    "operator_id": "op_42"
+  }
+}
+```
+
+---
+
+## Retrieve traces (for reports)
+
+Returns traces within a time window. Results are automatically filtered to the running use case of the connected operator.
+
+```http
+GET http://{Platform_Server}/api/v1/traces/{start_date}/&end_date={end_date}
+```
+
+| Parameter | Location | Description |
+|---|---|---|
+| `start_date` | Path | ISO 8601 start of the time window |
+| `end_date` | Query | ISO 8601 end of the time window |
+
+---
+
+## Postman collection
+
+[Historic-service.postman_collection.json](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Historic-service.postman_collection.json)
diff --git a/docs/api/recommendation-service.md b/docs/api/recommendation-service.md
new file mode 100644
index 00000000..ade12bf6
--- /dev/null
+++ b/docs/api/recommendation-service.md
@@ -0,0 +1,86 @@
+# Recommendation Service API
+
+The Recommendation Service is called by the HMI module when an operator requests help. It returns a list of recommendations combining AI-generated solutions and ontology-based solutions.
+
+> **Note:** This API is called internally by the platform. External integrators interact with recommendations indirectly — by receiving the selected recommendation's actions at their simulator callback endpoint (`POST http://{Simulator_server}/api/v1/recommendations`).
+
+**Base path:** `/cab_recommendation/api/v1`
+
+---
+
+## Get recommendations
+
+```http
+POST http://{Platform_Server}/cab_recommendation/api/v1/recommendation
+Content-Type: application/json
+```
+
+### Request body
+
+| Field | Type | Description |
+|---|---|---|
+| `event` | object | The current event object |
+| `context` | object | The current context object |
+
+### Response
+
+Returns an array of recommendation objects.
+
+### Recommendation object
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | string | Short label displayed on the HMI |
+| `description` | string | Detailed explanation of the recommendation |
+| `kpis` | array | *(Optional)* List of KPI objects for comparing recommendations side-by-side |
+| `agent_type` | string | Source of the recommendation — `AI` or `onto` (ontology) |
+| `actions` | array | List of actions to send to the simulator when this recommendation is chosen |
+
+### Example response
+
+```json
+[
+  {
+    "title": "Reroute traffic via L45",
+    "description": "Redirect load from L42 to L45 to bring L42 below rated capacity.",
+    "agent_type": "AI",
+    "kpis": [
+      { "name": "Load reduction on L42", "value": "18%", "unit": "%" },
+      { "name": "Estimated time to restore", "value": "5", "unit": "min" }
+    ],
+    "actions": [
+      { "type": "reroute", "line_from": "L42", "line_to": "L45", "load_percent": 70 }
+    ]
+  },
+  {
+    "title": "Reduce generation at G3",
+    "description": "Lower output at generator G3 to reduce grid stress.",
+    "agent_type": "onto",
+    "kpis": [
+      { "name": "Load reduction on L42", "value": "12%", "unit": "%" }
+    ],
+    "actions": [
+      { "type": "set_generation", "generator": "G3", "output_mw": 80 }
+    ]
+  }
+]
+```
+
+### Simulator callback
+
+When the operator selects a recommendation, the platform forwards its `actions` array to your simulator:
+
+```http
+POST http://{Simulator_server}/api/v1/recommendations
+Content-Type: application/json
+
+{ "actions": [ ... ] }
+```
+
+You must implement this endpoint in your simulator.
+
+---
+
+## Postman collection
+
+[Recommendation-service.postman_collection.json](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Recommendation-service.postman_collection.json)
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 00000000..a4255e47
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,84 @@
+# Getting Started
+
+This guide explains how to connect an external system (e.g. a simulator or data source) to the InteractiveAI platform.
+
+## Prerequisites
+
+- A running instance of the InteractiveAI platform. Replace `{Platform_Server}` in all API calls with your server's host and port (e.g. `localhost:8080`).
+- HTTP client of your choice (curl, Postman, your application's HTTP library).
+
+## Authentication
+
+All API calls require a bearer token. Obtain one first, then include it in every request:
+
+```http
+POST http://{Platform_Server}:3200/auth/token
+Content-Type: application/x-www-form-urlencoded
+
+username=publisher_test&password=test&grant_type=password&clientId=opfab-client
+```
+
+Then add the token to all subsequent requests:
+
+```http
+Authorization: Bearer <access_token>
+```
+
+See [Authentication](./api/authentication.md) for the full details and a Python example.
+
+## What you need to implement
+
+### 1. Send events to the platform
+
+Whenever a notable event occurs in your system, push it to the platform:
+
+```http
+POST http://{Platform_Server}/cab_event/api/v1/events
+Content-Type: application/json
+```
+
+See [Event Service API](./api/event-service.md) for the full payload schema and examples.
+
+### 2. Send context updates to the platform
+
+Keep the platform informed of the current operating context:
+
+```http
+POST http://{Platform_Server}/cab_context/api/v1/contexts
+Content-Type: application/json
+```
+
+See [Context Service API](./api/context-service.md) for the full payload schema and examples.
+
+### 3. Implement a recommendations endpoint (optional but recommended)
+
+When an operator selects a recommendation, the platform will call back your simulator with the list of actions to execute. You must expose this endpoint on your side:
+
+```http
+POST http://{Simulator_server}/api/v1/recommendations
+```
+
+The body will contain the actions array from the chosen recommendation (see [Recommendation Service](./api/recommendation-service.md)).
+
+## API summary
+
+| Service | Endpoint | Who calls it |
+|---|---|---|
+| Event | `POST /cab_event/api/v1/events` | **Your system** |
+| Context | `POST /cab_context/api/v1/contexts` | **Your system** |
+| Context (read) | `GET /cab_context/api/v1/contexts/$date` | HMI (internal) |
+| Historic | `POST /api/v1/traces` | Internal |
+| Historic (read) | `GET /api/v1/traces/$start_date/&end_date` | Internal |
+| Recommendation | `POST /cab_recommendation/api/v1/recommendation` | Internal (HMI) |
+| Capitalization | `POST /cab_capitalization/api/v1/feedbacks` | Internal (HMI) |
+| **Simulator callback** | `POST http://{Simulator_server}/api/v1/recommendations` | **Platform → Your system** |
+
+## Postman collections
+
+Ready-to-use Postman collections are available for each service:
+
+- [Event Service](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Event-service.postman_collection.json)
+- [Context Service](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Context-service.postman_collection.json)
+- [Historic Service](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Historic-service.postman_collection.json)
+- [Recommendation Service](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Recommendation-service.postman_collection.json)
+- [Capitalisation Service](https://github.com/IRT-SystemX/InteractiveAI/blob/main/docs/postman_collections/Capitalisation-service.postman_collection.json)
diff --git a/docs/img/GeneralWorkflow.png b/docs/img/GeneralWorkflow.png
new file mode 100644
index 00000000..12ff2d59
Binary files /dev/null and b/docs/img/GeneralWorkflow.png differ
diff --git a/docs/img/InteractiveAI_AIAgent.png b/docs/img/InteractiveAI_AIAgent.png
new file mode 100644
index 00000000..89f87102
Binary files /dev/null and b/docs/img/InteractiveAI_AIAgent.png differ
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100644
index 00000000..f66b7fe8
--- /dev/null
+++ b/docs/overview.md
@@ -0,0 +1,52 @@
+# InteractiveAI Platform — Overview
+
+InteractiveAI is an open-source framework designed for industries that need to monitor and manage complex networks. It integrates human-machine interactions and human expertise to optimize AI performance, and streamlines the integration of advanced AI modules for demanding operational environments.
+
+## Architecture
+
+The platform follows a 3-tier architecture:
+
+| Layer | Role |
+|---|---|
+| **Presentation (Frontend)** | Browser rendering and user interaction (HMI module) |
+| **Services** | Business logic, AI modules, and application rules |
+| **Data** | Persistent storage — databases, files, knowledge base, and ontology |
+
+An HTTP **Gateway** sits at the entry point of the services layer and routes incoming requests to the appropriate service based on the API called.
+
+## Services
+
+Services are split into two categories:
+
+### Support Services
+Pure software services (no AI) that underpin the supervision feature:
+
+- **Event Service** — Ingests incoming messages, categorizes and prioritizes events, sends notifications to the frontend, and maintains the timeline.
+- **Context Service** — Collects and analyzes internal and external context data (environment, operator cognitive load, mission parameters) and keeps the current context up to date.
+- **Historic Service** — Tracks all events and operator actions in a log database.
+
+### AI / Business Services
+
+- **Recommendation Service** — Handles requests for AI-generated and ontology-based recommendations in response to events.
+- **Knowledge Acquisition Service** — Manages the knowledge base (implicitly integrated into the Recommendation Service).
+- **Capitalization Service** — Collects and stores operator feedback (chosen/rejected recommendations) for future model improvement.
+
+## Integration Points for External Systems
+
+External systems (simulators, data sources) only need to call **two** APIs to communicate with the platform:
+
+1. **Event API** — to push events into the platform
+2. **Context API** — to push context updates
+
+All other APIs are consumed internally by the platform's services and HMI module.
+
+When the operator selects a recommendation, the platform will call back an endpoint on the simulator side:
+```
+POST http://{Simulator_server}/api/v1/recommendations
+```
+You must implement this endpoint in your simulator to receive the selected actions.
+
+## Source Code
+
+- Platform repository: [AINETUS/InteractiveAI](https://github.com/ainetus/InteractiveAI)
+- Postman collections: [`docs/postman_collections/`](https://github.com/IRT-SystemX/InteractiveAI/tree/main/docs/postman_collections)