docs: implement Perry Human-in-the-Loop (HITL) technical documentation

custom_addons/docs/addons/perry-human-in-the-loop.md

@@ -0,0 +1,46 @@
+The **HITL** system is Perry's "safety catch." Instead of allowing the AI to write directly to sensitive models (like Payments or CRM Leads), Perry prepares a **Pending Action**. This action acts as a draft containing all the necessary metadata, which a human user must then review, confirm, or cancel.
+
+##  Model overview: `perry.pending.action`
+
+This model serves as a temporary staging area for AI-generated intents. It stores the raw data in a JSON payload and provides a user-friendly interface for execution.
+
+### Core Fields:
+*   **Action title (`name`)**: A descriptive name for the task (e.g., "Schedule Meeting: Project Review").
+*   **Action type (`action_type`)**: Defines the target Odoo module:
+    *   `lead`: Creates a CRM Opportunity.
+    *   `payment`: Registers an Accounting Payment.
+    *   `calendar`: Creates a Calendar Event.
+*   **Payload (`payload`)**: A hidden text field containing the raw JSON data extracted by the AI agents.
+*   **Status (`state`)**: Manages the lifecycle: `draft` $\to$ `pending` $\to$ `done` or `cancelled`.
+
+## Key features
+
+### 1. Dynamic data summary
+To avoid forcing users to read raw JSON, the module includes a computed **Summary HTML** field.
+*   **Logic**: It parses the `payload` and generates a clean, responsive HTML table.
+*   **User experience**: Users see a clear breakdown of "Recipient," "Amount," or "Date" directly on the Odoo form before clicking confirm.
+
+### 2. The execution engine (`action_confirm`)
+When a user clicks **Confirm**, the module triggers specific Odoo logic based on the action type:
+
+*   **CRM leads**: Creates a new `crm.lead` record using `sudo()` to ensure permissions don't block the AI's intent.
+*   **Accounting payments**: 
+    *   Performs an `ilike` search for the **Partner** and **Journal**.
+    *   Creates an `account.payment` record.
+    *   Automatically triggers `.action_post()` to move the payment out of draft state.
+*   **Calendar events**: 
+    *   Parses naive timestamps.
+    *   Calculates durations and sets the UTC offset (defaulting to -2 hours for specific regional logic).
+    *   Creates the `calendar.event`.
+
+### 3. Safety first (`action_cancel`)
+If the AI extracted the wrong data or the user changes their mind, the `action_cancel` method simply marks the record as `cancelled`. This prevents the data from ever touching the core Odoo business models.
+
+
+## Observability (Logfire)
+
+The HITL module is deeply instrumented with **Logfire** to provide a full audit trail of human decisions:
+*   **Computation Traces**: Logs every time a summary is rendered.
+*   **Lookup Logs**: In payments, it logs whether the Partner or Journal were successfully found.
+*   **Execution Spans**: Every confirmation is wrapped in a span that logs the final record ID created in Odoo.
+*   **Validation Errors**: If a journal isn't found or a payment fails to post, Logfire captures the exception before Odoo shows the user a friendly error message.