From 7b2adf9d9dab138341daedc3bfab52e4e495b1fa Mon Sep 17 00:00:00 2001
From: Alexander Minges <alexander.minges@uni-due.de>
Date: Tue, 10 Feb 2026 16:29:31 +0100
Subject: [PATCH] docs(matrix): document raw html escaping in markdown renderer

---
 nanobot/channels/matrix.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/nanobot/channels/matrix.py b/nanobot/channels/matrix.py
index 8240b51..f00f321 100644
--- a/nanobot/channels/matrix.py
+++ b/nanobot/channels/matrix.py
@@ -32,6 +32,10 @@ MATRIX_HTML_FORMAT = "org.matrix.custom.html"
 #   that Matrix clients (e.g. Element/FluffyChat) can render consistently.
 # We intentionally avoid plugins that emit less-portable tags to keep output
 # predictable across clients.
+# escape=True is intentional: raw HTML from model output is rendered as text,
+# not as live HTML. This includes Matrix-specific raw snippets such as
+# <span data-mx-...> and <div data-mx-maths>, unless we later add explicit
+# structured support for those features.
 MATRIX_MARKDOWN = create_markdown(
     escape=True,
     plugins=["table", "strikethrough", "url", "superscript", "subscript"],