Add human-led conversation learning loop

docs/data-flow.md

@@ -137,3 +137,17 @@ Use three categories consistently:
 - Human-required: policy or safety cannot continue autonomously; stop automation and surface an attention item.
 
 Avoid converting errors into generic skips. Operational diagnosis depends on preserving which stage failed and why.
+## Human learning loop
+
+After a room has an authoritative Matrix timeline, `ChatService` records the canonical response outcome and invokes the account-scoped learning observer. The observer:
+
+1. reconciles opener, automation-claim, exchange-library, manual-dashboard, recipient, and legacy events;
+2. stores text-minimising event provenance with an attribution confidence;
+3. finds received-image outcomes and the manual decisions that preceded them;
+4. assigns human-created, human-improved, human-completed, autonomous, recipient-initiated, or uncertain credit;
+5. stores bounded, identifier-redacted decision context; and
+6. leaves new trajectories provisional until the maturity window passes.
+
+Full chat synchronization naturally backfills older rooms. Upserts are keyed by account, room, and outcome event, so the pass is repeatable. A later negative canonical outcome invalidates both the trajectory and every derived decision.
+
+Retrieval is account-scoped and excludes the current conversation. It uses explicit human and autonomous quotas, same-policy/stage preference, confidence filtering, and a generation audit ledger. With the default configuration it runs in shadow mode: selected IDs are recorded but examples are not put into the prompt.