docs: implement Odoo Addons README and extensibility overview

custom_addons/README.md

@@ -0,0 +1,30 @@
+# Odoo addons
+
+This module contains the custom Odoo addons designed to bridge the Odoo ERP with the **Perry AI ecosystem**. 
+
+These addons ensure that Perry can "listen" to communications, process intents asynchronously, and stage sensitive operations for human verification. Every addon follows a non-blocking architecture and is fully instrumented for real-time observability.
+
+## Structure
+
+- `perry_webhook`: Intercepts Odoo messages via the `mail.message` model and dispatches them to the Perry Ingest API using background threads.
+- `perry_hitl`: Implements the "Human-in-the-Loop" safety layer, managing the `perry.pending.action` model for staging AI intents.
+
+## Core features
+
+### Human-in-the-Loop (HITL)
+To maintain data integrity, sensitive operations (Payments, Leads, Calendar) are never created directly by the AI. They are staged as "Pending Actions" where a human must review the extracted data and click "Confirm" to execute the final Odoo record creation.
+
+### Non-blocking architecture
+All external API calls are executed using Python's `threading` library. This ensures that the Odoo UI remains responsive and the message input bar clears instantly, while Perry processes the request in a background thread with its own database cursor.
+
+### Full observability
+Every hook, API call, and human confirmation is wrapped in **Logfire spans**. This provides a complete audit trail from the moment a user types a message to the final execution of an administrative task.
+
+## Documentation
+
+### Addon-specific Documentation
+- [Perry Webhook Addon](docs/addons/perry-webhook.md) — How messages are intercepted and dispatched.
+- [Perry Human-in-the-Loop](docs/addons/perry-human-in-the-loop.md) — Technical details on the staging and confirmation logic.
+
+### Integration Standards
+- [Logfire Configuration](docs/logfire.md) — Setting up traceability across the Odoo instance.