diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5381de6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# Testing Odoo: Perry ERP Environment
+
+![Odoo](https://img.shields.io/badge/Odoo-v17-875A7B?style=for-the-badge&logo=odoo&logoColor=white)
+![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15-4169E1?style=for-the-badge&logo=postgresql&logoColor=white)
+![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)
+
+**Testing Odoo** is the dedicated ERP environment and frontend interface for **Perry**, our multi-agent AI orchestrator. 
+
+This repository contains a containerized Odoo 17 instance pre-configured with a suite of custom addons. It handles user interactions via the Discuss app, captures real-time webhooks, enforces Human-in-the-Loop (HITL) validations and acts as the database backend for the AI's Model Context Protocol (MCP) tools.
+
+---
+
+## Documentation
+
+Detailed documentation for the architecture, standards and specific features of this Odoo environment can be found in these directories:
+
+*   **[Traceability & Observability Guide](./custom_addons/docs/README.md)**: A complete manual on how Pydantic Logfire is used across the ecosystem, including setup instructions, code instrumentation standards and how to navigate the live dashboard.
+
+---
+
+## Custom Addons Ecosystem
+
+The system is extended through a modular architecture located in the `custom_addons/` directory:
+
+* **`perry_auto_reply`**: A lightweight auto-responder for private Odoo channels. It intercepts incoming messages directed at the AI and instantly replies with a placeholder acknowledgment, providing immediate user feedback before the complex AI generation finishes.
+
+*   **`perry_webhook`**: Captures messages from Odoo's chat interface, displays real-time typing indicators and forwards payloads to the FastAPI brain via background threads.
+
+*   **`perry_human_loop`**: Intercepts critical actions (e.g., payments, leads) proposed by the AI and creates a pending action queue for mandatory human validation before execution.
+
+---
+
+## Key features
+
+*   **Seamless AI UX**: Real-time WebSocket integration ensuring users see instant AI responses without page reloads.
+*   **Secure execution**: The backend acts as a strict gatekeeper. No AI agent can write critical data to the database without triggering the Human-in-the-Loop confirmation pipeline.
+*   **End-to-End traceability**: Fully integrated with **[Pydantic Logfire](https://logfire.pydantic.dev/)** to trace the complete lifecycle of webhook events and internal Odoo model logic.
+*   **Ready-to-Use Docker stack**: Bundled with Odoo and PostgreSQL for an immediate plug-and-play development experience.
+
+---
+
+## Code Quality & Standards
+
+We maintain a rigorous quality standard across all custom Odoo addons:
+*   **Linting & Formatting**: Clean Python code guaranteed by `ruff` and standard Odoo guidelines.
+*   **Observability**: Strict rules for contextual spans and error handling inside Odoo's `@api.model` decorators.
+*   **Isolation**: No hardcoded paths; all inter-module dependencies are explicitly declared in `__manifest__.py` files.
+
+---
+
+## Installation and deployment
+
+This environment works in tandem with the **ingest-api** (Perry's brain). Both must run on the same Docker network to communicate effectively.
+
+### 1. Network preparation
+Create the shared Docker network to allow communication between Odoo and the AI APIs:
+```bash
+docker network create perry-network
+```
+
+### 2. Odoo setup (`testing-odoo`)
+Clone this repository, configure your environment variables and launch the ERP:
+```bash
+git clone https://github.com/your-user/testing-odoo.git
+cd testing-odoo
+```
+Create a `.env` file from the example (ensure `LOGFIRE_TOKEN` is set for observability), then build the containers:
+```bash
+docker-compose up -d --build
+```
+*Odoo will be available at `http://localhost:8069`.*
+
+### 3. Connect to Perry (`ingest-api`)
+To complete the system, deploy the orchestrator repository:
+```bash
+cd ..
+git clone https://github.com/your-user/ingest-api.git
+cd ingest-api
+docker-compose up -d --build
+```
+
+### 4. Link containers to the network
+Attach both running instances to the shared network:
+```bash
+docker network connect perry-network testing-odoo
+docker network connect perry-network ingest-api
+```
+
+### 5. Module installation
+1. Log into Odoo (Developer Mode must be enabled).
+2. Go to **Apps** > **Update Apps List**.
+3. Search for `perry` and install the custom modules (`Perry Webhook`, `Perry Human Loop`).