From f89daf2e62a749402de1bb0a994fc1cbaea2f140 Mon Sep 17 00:00:00 2001
From: Steven Chand <stevenchand21@gmail.com>
Date: Thu, 20 Aug 2026 17:20:05 -0700
Subject: [PATCH 1/6] [SC-17911] Send log_text Markdown without script tags

---
 tests/test_api_client.py | 58 +++++++++++++++++++++++++++++++++++++---
 validmind/api_client.py  | 56 +++++++++++++++++++++++++++++++-------
 2 files changed, 100 insertions(+), 14 deletions(-)

diff --git a/tests/test_api_client.py b/tests/test_api_client.py
index 971dbce2e..122202b54 100644
--- a/tests/test_api_client.py
+++ b/tests/test_api_client.py
@@ -315,9 +315,8 @@ def test_log_text_generates_text_and_logs_metadata(
             data=json.dumps(
                 {
                     "content_id": "dataset_summary_text",
-                    "text": md_to_html(
-                        "## Generated Summary\nGenerated content.", mathml=True
-                    ),
+                    "text": "## Generated Summary\nGenerated content.",
+                    "text_format": "markdown",
                 }
             ),
         )
@@ -366,7 +365,58 @@ def test_log_text_logs_metadata_with_section_id(
             data=json.dumps(
                 {
                     "content_id": "dataset_summary_text",
-                    "text": md_to_html("Generated content.", mathml=True),
+                    "text": "Generated content.",
+                    "text_format": "markdown",
+                }
+            ),
+        )
+
+    @patch("aiohttp.ClientSession.post")
+    def test_log_text_sends_tex_as_waf_safe_markdown(self, mock_post: MagicMock):
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        mock_post.return_value = MockAsyncResponse(
+            200,
+            json={
+                "content_id": "text_woe_equation",
+                "text": '<p><script type="math/tex">WOE</script></p>',
+            },
+        )
+
+        self.run_async(
+            api_client.alog_text,
+            "text_woe_equation",
+            text=equation,
+        )
+
+        mock_post.assert_called_once_with(
+            f"{os.environ['VM_API_HOST']}/log_metadata",
+            data=json.dumps(
+                {
+                    "content_id": "text_woe_equation",
+                    "text": equation,
+                    "text_format": "markdown",
+                }
+            ),
+        )
+        request_body = mock_post.call_args.kwargs["data"]
+        self.assertNotIn("<script", request_body)
+
+    @patch("aiohttp.ClientSession.post")
+    def test_log_text_preserves_explicit_html_payload(self, mock_post: MagicMock):
+        html = "<p>Already converted</p>"
+        mock_post.return_value = MockAsyncResponse(
+            200,
+            json={"content_id": "existing_html", "text": html},
+        )
+
+        self.run_async(api_client.alog_text, "existing_html", text=html)
+
+        mock_post.assert_called_once_with(
+            f"{os.environ['VM_API_HOST']}/log_metadata",
+            data=json.dumps(
+                {
+                    "content_id": "existing_html",
+                    "text": html,
                 }
             ),
         )
diff --git a/validmind/api_client.py b/validmind/api_client.py
index b3de39431..86dac67d8 100644
--- a/validmind/api_client.py
+++ b/validmind/api_client.py
@@ -588,6 +588,7 @@ async def alog_metadata(
     text: Optional[str] = None,
     _json: Optional[Dict[str, Any]] = None,
     section_id: Optional[str] = None,
+    text_format: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Logs free-form metadata to ValidMind API.
 
@@ -597,6 +598,9 @@ async def alog_metadata(
         _json (dict, optional): Free-form key-value pairs to assign to the metadata. Defaults to None.
         section_id (str, optional): Section ID to append the text block to when the
             content ID does not already exist.
+        text_format (str, optional): Format of ``text``. New ``log_text`` calls use
+            ``markdown`` so conversion happens after the request passes through the
+            WAF. Omitted for backward-compatible HTML payloads.
 
     Raises:
         Exception: If the API call fails.
@@ -609,6 +613,8 @@ async def alog_metadata(
         metadata_dict["text"] = text
     if _json is not None:
         metadata_dict["json"] = _json
+    if text_format is not None:
+        metadata_dict["text_format"] = text_format
 
     request_params = {}
     if section_id:
@@ -808,11 +814,18 @@ def generate_qualitative_text(text_generation_data: Dict[str, Any]) -> Dict[str,
     return r.json()
 
 
-def _normalize_logged_text(text: str, field_name: str) -> str:
-    """Validate text content and convert Markdown to HTML when needed."""
+def _validate_logged_text(text: str, field_name: str) -> str:
+    """Validate text accepted by log_text."""
     if not isinstance(text, str) or not text:
         raise ValueError(f"`{field_name}` must be a non-empty string")
 
+    return text
+
+
+def _normalize_logged_text(text: str, field_name: str) -> str:
+    """Validate text content and convert Markdown to HTML for local rendering."""
+    text = _validate_logged_text(text, field_name)
+
     if not is_html(text):
         return md_to_html(text, mathml=True)
 
@@ -828,7 +841,7 @@ def _validate_manual_log_text_args(
     if context is not None:
         raise ValueError("`context` is only supported when `text` is omitted")
 
-    return _normalize_logged_text(text, "text")
+    return _validate_logged_text(text, "text")
 
 
 def _build_log_text_generation_request(
@@ -860,13 +873,13 @@ def _build_log_text_generation_request(
     return request_data
 
 
-def _generate_log_text(
+def _generate_log_text_source(
     content_id: str,
     prompt: Optional[str],
     context: Optional[Dict[str, Any]],
     section_id: Optional[str] = None,
 ) -> str:
-    """Generate text for log_text and normalize it to HTML."""
+    """Generate and validate source text without converting it to HTML."""
     request_data = _build_log_text_generation_request(
         content_id,
         prompt,
@@ -874,6 +887,22 @@ def _generate_log_text(
         section_id=section_id,
     )
     generated_text = generate_qualitative_text(request_data)["content"]
+    return _validate_logged_text(generated_text, "generated text")
+
+
+def _generate_log_text(
+    content_id: str,
+    prompt: Optional[str],
+    context: Optional[Dict[str, Any]],
+    section_id: Optional[str] = None,
+) -> str:
+    """Generate text and normalize it to HTML for local result rendering."""
+    generated_text = _generate_log_text_source(
+        content_id,
+        prompt,
+        context,
+        section_id=section_id,
+    )
     return _normalize_logged_text(generated_text, "generated text")
 
 
@@ -902,14 +931,21 @@ async def alog_text(
     if text is not None:
         text = _validate_manual_log_text_args(text, prompt, context)
     else:
-        text = _generate_log_text(
+        text = _generate_log_text_source(
             content_id,
             prompt,
             context,
             section_id=section_id,
         )
 
-    return await alog_metadata(content_id, text, _json, section_id=section_id)
+    text_format = None if is_html(text) else "markdown"
+    return await alog_metadata(
+        content_id,
+        text,
+        _json,
+        section_id=section_id,
+        text_format=text_format,
+    )
 
 
 def log_text(
@@ -924,9 +960,9 @@ def log_text(
 
     Args:
         content_id (str): Unique content identifier for the text.
-        text (str, optional): The text to log. Will be converted to HTML with
-            MathML support when Markdown is provided. If omitted, text is
-            generated using the qualitative text generation backend.
+        text (str, optional): The text to log. Markdown is sent to the backend for
+            HTML and math conversion. If omitted, text is generated using the
+            qualitative text generation backend.
         prompt (str, optional): Custom prompt used for AI-assisted text
             generation. Only supported when `text` is omitted.
         context (dict, optional): Context object for AI-assisted text

From 24b20780fcd0b921d41c2e46486aa695942af42b Mon Sep 17 00:00:00 2001
From: Steven Chand <stevenchand21@gmail.com>
Date: Thu, 20 Aug 2026 17:48:27 -0700
Subject: [PATCH 2/6] [SC-17911] Keep result description payloads WAF-safe

---
 tests/test_api_client.py             |  27 +++++++
 tests/test_client.py                 |  11 +--
 tests/test_results.py                | 104 ++++++++++++++++++++++++---
 tests/test_test_descriptions.py      |  14 +++-
 validmind/ai/utils.py                |   7 +-
 validmind/client.py                  |  10 ++-
 validmind/experimental/agents.py     |   4 +-
 validmind/tests/output.py            |   3 +
 validmind/tests/run.py               |   7 +-
 validmind/vm_models/result/result.py |  54 ++++++++++----
 validmind/vm_models/result/utils.py  |  16 ++++-
 11 files changed, 220 insertions(+), 37 deletions(-)

diff --git a/tests/test_api_client.py b/tests/test_api_client.py
index 122202b54..2d0a42bf8 100644
--- a/tests/test_api_client.py
+++ b/tests/test_api_client.py
@@ -23,6 +23,7 @@
 )
 from validmind.utils import md_to_html
 from validmind.vm_models.figure import Figure
+from validmind.vm_models.result.utils import update_metadata
 
 loop = asyncio.new_event_loop()
 
@@ -247,6 +248,32 @@ def test_log_metadata_with_section_id(self, mock_post: MagicMock):
             ),
         )
 
+    @patch("aiohttp.ClientSession.post")
+    def test_result_update_metadata_sends_waf_safe_markdown(
+        self, mock_post: MagicMock
+    ):
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        mock_post.return_value = MockAsyncResponse(200, json={"cuid": "abc1234"})
+
+        self.run_async(
+            update_metadata,
+            "test_description:equation::default",
+            equation,
+            text_format="markdown",
+        )
+
+        mock_post.assert_called_once_with(
+            f"{os.environ['VM_API_HOST']}/log_metadata",
+            data=json.dumps(
+                {
+                    "content_id": "test_description:equation::default",
+                    "text": equation,
+                    "text_format": "markdown",
+                }
+            ),
+        )
+        self.assertNotIn("<script", mock_post.call_args.kwargs["data"])
+
     @patch("aiohttp.ClientSession.post")
     def test_log_test_result(self, mock_post):
         result = {
diff --git a/tests/test_client.py b/tests/test_client.py
index 53a059b6b..e786925b3 100644
--- a/tests/test_client.py
+++ b/tests/test_client.py
@@ -206,11 +206,11 @@ def test_get_content_ids_for_multiple_sections(self):
 
 
 class TestRunTextGeneration(TestCase):
-    @mock.patch(
-        "validmind.client.api_client._generate_log_text",
-        return_value="<p>Generated text</p>",
-    )
+    @mock.patch("validmind.client.api_client._generate_log_text_source")
     def test_run_text_generation(self, mock_generate_text):
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        mock_generate_text.return_value = equation
+
         result = run_text_generation(
             content_id="dataset_summary_text",
             prompt="Summarize the dataset.",
@@ -224,7 +224,8 @@ def test_run_text_generation(self, mock_generate_text):
         self.assertEqual(result.prompt, "Summarize the dataset.")
         self.assertEqual(result.section_id, "data_description")
         self.assertEqual(result.context, {"content_ids": ["train_dataset"]})
-        self.assertEqual(result.description, "<p>Generated text</p>")
+        self.assertIn('<script type="math/tex">', result.description)
+        self.assertEqual(result._description_source, equation)
         self.assertTrue(result._was_description_generated)
         self.assertIn("validmind", result.metadata)
         self.assertIn("timestamp", result.metadata)
diff --git a/tests/test_results.py b/tests/test_results.py
index 035dadab9..c0632bdd7 100644
--- a/tests/test_results.py
+++ b/tests/test_results.py
@@ -20,6 +20,8 @@
 
 from validmind.vm_models.figure import Figure
 from validmind.errors import InvalidParameterError
+from validmind.tests.run import run_test
+from validmind.utils import md_to_html
 
 loop = asyncio.new_event_loop()
 
@@ -99,6 +101,30 @@ def test_test_result_initialization(self):
         self.assertEqual(test_result.metric, 0.95)
         self.assertTrue(test_result.passed)
 
+    @patch("validmind.tests.run._get_run_metadata", return_value={})
+    @patch("validmind.tests.run.get_result_description")
+    @patch("validmind.tests.run._run_test")
+    def test_run_test_retains_markdown_description_source(
+        self, mock_run_test, mock_get_description, _mock_run_metadata
+    ):
+        """Default test descriptions retain Markdown alongside rendered HTML."""
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        mock_run_test.return_value = TestResult(
+            result_id="validmind.test.Equation",
+            doc=equation,
+            inputs={},
+        )
+        mock_get_description.return_value = md_to_html(equation, mathml=True)
+
+        result = run_test(
+            test_id="validmind.test.Equation",
+            generate_description=False,
+            show=False,
+        )
+
+        self.assertIn('<script type="math/tex">', result.description)
+        self.assertEqual(result._description_source, equation)
+
     def test_test_result_add_table(self):
         """Test adding tables to TestResult"""
         test_result = TestResult(result_id="test_1")
@@ -228,6 +254,48 @@ async def test_text_generation_result_log_async(self, mock_log_text):
             section_id=None,
         )
 
+    @patch("validmind.vm_models.result.result.api_client.alog_text")
+    @patch.object(TextGenerationResult, "_get_client_config")
+    def test_text_generation_result_logs_markdown_source(
+        self, mock_get_client_config, mock_log_text
+    ):
+        """Generated result HTML stays local while its Markdown is logged."""
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        text_result = TextGenerationResult(
+            result_id="text_1",
+            content_id="dataset_summary_text",
+            description=md_to_html(equation, mathml=True),
+            _description_source=equation,
+        )
+        mock_get_client_config.return_value = type(
+            "MockConfig",
+            (),
+            {
+                "documentation_template": {
+                    "sections": [
+                        {
+                            "id": "data_description",
+                            "contents": [
+                                {
+                                    "content_id": "dataset_summary_text",
+                                    "content_type": "text",
+                                }
+                            ],
+                        }
+                    ]
+                }
+            },
+        )()
+
+        self.run_async(text_result.log_async)
+
+        self.assertIn('<script type="math/tex">', text_result.description)
+        mock_log_text.assert_called_once_with(
+            content_id=f"dataset_summary_text::{DEFAULT_REVISION_NAME}",
+            text=equation,
+            section_id=None,
+        )
+
     @patch("validmind.vm_models.result.result.api_client.alog_text")
     async def test_text_generation_result_log_async_with_section_id(self, mock_log_text):
         """Test async logging of TextGenerationResult forwards section_id"""
@@ -344,33 +412,53 @@ def test_validate_log_config(self):
         with self.assertRaises(InvalidParameterError):
             test_result.validate_log_config(invalid_type_config)
 
-    @patch("validmind.api_client.update_metadata")
-    async def test_metadata_update_content_id_handling(self, mock_update_metadata):
+    @patch("validmind.vm_models.result.result.update_metadata")
+    @patch("validmind.api_client.alog_test_result")
+    def test_metadata_update_content_id_handling(
+        self, mock_log_test_result, mock_update_metadata
+    ):
         """Test metadata update with different content_id scenarios"""
         # Test case 1: With content_id
         test_result = TestResult(
             result_id="test_1",
             description="Test description",
+            inputs={},
             _was_description_generated=False,
         )
-        await test_result.log_async(content_id="custom_content_id")
+        self.run_async(test_result.log_async, content_id="custom_content_id")
         mock_update_metadata.assert_called_with(
-            content_id="custom_content_id::default", text="Test description"
+            content_id=f"custom_content_id::{DEFAULT_REVISION_NAME}",
+            text="Test description",
         )
 
         # Test case 2: Without content_id
         mock_update_metadata.reset_mock()
-        await test_result.log_async()
+        self.run_async(test_result.log_async)
         mock_update_metadata.assert_called_with(
-            content_id="test_description:test_1::default", text="Test description"
+            content_id=f"test_description:test_1::{DEFAULT_REVISION_NAME}",
+            text="Test description",
         )
 
         # Test case 3: With AI generated description
         test_result._was_description_generated = True
         mock_update_metadata.reset_mock()
-        await test_result.log_async()
+        self.run_async(test_result.log_async)
+        mock_update_metadata.assert_called_with(
+            content_id=f"test_description:test_1::{AI_REVISION_NAME}",
+            text="Test description",
+        )
+
+        # Test case 4: Rendered HTML remains local and raw Markdown is sent safely
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        test_result.description = md_to_html(equation, mathml=True)
+        test_result._description_source = equation
+        mock_update_metadata.reset_mock()
+        self.run_async(test_result.log_async)
+        self.assertIn('<script type="math/tex">', test_result.description)
         mock_update_metadata.assert_called_with(
-            content_id="test_description:test_1::ai", text="Test description"
+            content_id=f"test_description:test_1::{AI_REVISION_NAME}",
+            text=equation,
+            text_format="markdown",
         )
 
     def test_test_result_metric_values_integration(self):
diff --git a/tests/test_test_descriptions.py b/tests/test_test_descriptions.py
index 0aa7e7a1f..97cb3f075 100644
--- a/tests/test_test_descriptions.py
+++ b/tests/test_test_descriptions.py
@@ -11,6 +11,7 @@
     _truncate_summary,
     _truncate_text_simple,
 )
+from validmind.ai.utils import DescriptionFuture
 
 
 class TestTokenEstimation(unittest.TestCase):
@@ -29,6 +30,17 @@ def test_estimate_tokens_simple(self):
         text_400 = "a" * 400
         self.assertEqual(_estimate_tokens_simple(text_400), 100)
 
+    def test_description_future_retains_markdown_source(self):
+        """AI test descriptions retain raw Markdown for WAF-safe logging."""
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        description = DescriptionFuture((equation, True))
+
+        rendered, was_generated = description.get_description()
+
+        self.assertTrue(was_generated)
+        self.assertIn('<script type="math/tex">', rendered)
+        self.assertEqual(description.markdown_source, equation)
+
     def test_truncate_text_simple_no_truncation(self):
         """Test that short text is not truncated."""
         short_text = "This is a short text."
@@ -135,5 +147,3 @@ def test_fallback_path(self, mock_truncate, mock_estimate, mock_encoding):
         mock_encoding.decode.assert_not_called()
 
         self.assertEqual(result, "fallback_result")
-
-
diff --git a/validmind/ai/utils.py b/validmind/ai/utils.py
index 2e79e395f..1eebec6bb 100644
--- a/validmind/ai/utils.py
+++ b/validmind/ai/utils.py
@@ -8,7 +8,7 @@
 from openai import AzureOpenAI, OpenAI
 
 from ..logging import get_logger
-from ..utils import md_to_html
+from ..utils import is_html, md_to_html
 
 logger = get_logger(__name__)
 
@@ -38,6 +38,7 @@ class DescriptionFuture:
 
     def __init__(self, future):
         self._future = future
+        self.markdown_source = None
 
     def get_description(self):
         if isinstance(self._future, tuple):
@@ -46,7 +47,9 @@ def get_description(self):
             # This will block until the future is completed
             description = self._future.result()
 
-        return md_to_html(description[0], mathml=True), description[1]
+        source, was_generated = description
+        self.markdown_source = source if not is_html(source) else None
+        return md_to_html(source, mathml=True), was_generated
 
 
 def _get_google_api_key():
diff --git a/validmind/client.py b/validmind/client.py
index c6fea1cde..19a5302b4 100644
--- a/validmind/client.py
+++ b/validmind/client.py
@@ -38,7 +38,7 @@
 from .test_suites import get_by_id as get_test_suite_by_id
 from .tests.run import _get_run_metadata
 from .utils import display as vm_display
-from .utils import get_dataset_info, get_model_info
+from .utils import get_dataset_info, get_model_info, is_html
 from .vm_models import TestSuite, TestSuiteRunner
 from .vm_models.dataset import DataFrameDataset, PolarsDataset, TorchDataset, VMDataset
 from .vm_models.html_progress import HTMLLabel, HTMLProgressBar
@@ -479,9 +479,12 @@ def run_text_generation(
         A TextGenerationResult containing the generated text.
     """
     start_time = time.perf_counter()
-    description = api_client._generate_log_text(
+    description_source = api_client._generate_log_text_source(
         content_id, prompt, context, section_id=section_id
     )
+    description = api_client._normalize_logged_text(
+        description_source, "generated text"
+    )
     metadata = _get_run_metadata(duration_seconds=time.perf_counter() - start_time)
     result = TextGenerationResult(
         result_id=content_id,
@@ -494,6 +497,9 @@ def run_text_generation(
         section_id=section_id,
         context=context,
         _was_description_generated=True,
+        _description_source=(
+            description_source if not is_html(description_source) else None
+        ),
     )
 
     if show:
diff --git a/validmind/experimental/agents.py b/validmind/experimental/agents.py
index ce0d7249f..a95332527 100644
--- a/validmind/experimental/agents.py
+++ b/validmind/experimental/agents.py
@@ -54,7 +54,8 @@ def run_task(
     else:
         raise ValueError(f"Unsupported task: {task}")
 
-    if not is_html(generated_text):
+    description_source = generated_text if not is_html(generated_text) else None
+    if description_source is not None:
         generated_text = md_to_html(generated_text, mathml=True)
 
     # Create a test result with the generated text
@@ -68,6 +69,7 @@ def run_task(
         section_id=input.get("section_id"),
         context=input.get("context"),
         _was_description_generated=True,
+        _description_source=description_source,
     )
     if show:
         result.show()
diff --git a/validmind/tests/output.py b/validmind/tests/output.py
index d0f3835b8..59c793904 100644
--- a/validmind/tests/output.py
+++ b/validmind/tests/output.py
@@ -184,7 +184,10 @@ def can_handle(self, item: Any) -> bool:
 
     def process(self, item: Any, result: TestResult) -> None:
         if not is_html(item):
+            result._description_source = item
             item = md_to_html(item, mathml=True)
+        else:
+            result._description_source = None
 
         result.description = item
 
diff --git a/validmind/tests/run.py b/validmind/tests/run.py
index 194a80bec..7c1cbb88e 100644
--- a/validmind/tests/run.py
+++ b/validmind/tests/run.py
@@ -16,7 +16,7 @@
 from validmind.errors import MissingRequiredTestInputError
 from validmind.input_registry import input_registry
 from validmind.logging import get_logger
-from validmind.utils import test_id_to_name
+from validmind.utils import is_html, test_id_to_name
 from validmind.vm_models.input import VMInput
 from validmind.vm_models.result import TestResult
 
@@ -451,7 +451,7 @@ def run_test(  # noqa: C901
         result = post_process_fn(result)
 
     if not result.description:
-        result.description = get_result_description(
+        description = get_result_description(
             test_id=test_id,
             test_description=result.doc,
             tables=result.tables,
@@ -463,6 +463,9 @@ def run_test(  # noqa: C901
             additional_context=additional_context,
             params=result.params,
         )
+        result.description = description
+        if isinstance(description, str) and result.doc and not is_html(result.doc):
+            result._description_source = result.doc
 
     if show:
         result.show()
diff --git a/validmind/vm_models/result/result.py b/validmind/vm_models/result/result.py
index 9a72637d5..e60533ba6 100644
--- a/validmind/vm_models/result/result.py
+++ b/validmind/vm_models/result/result.py
@@ -20,7 +20,13 @@
 from ...ai.utils import DescriptionFuture
 from ...errors import InvalidParameterError
 from ...logging import get_logger, log_api_operation
-from ...utils import HumanReadableEncoder, display, run_async, test_id_to_name
+from ...utils import (
+    HumanReadableEncoder,
+    display,
+    md_to_html,
+    run_async,
+    test_id_to_name,
+)
 from ..figure import Figure, create_figure
 from ..html_renderer import StatefulHTMLRenderer
 from ..input import VMInput
@@ -36,6 +42,17 @@
 logger = get_logger(__name__)
 
 
+def _description_transport(rendered_description, markdown_source):
+    """Use Markdown only while it still corresponds to the rendered description."""
+    if (
+        markdown_source is not None
+        and md_to_html(markdown_source, mathml=True) == rendered_description
+    ):
+        return markdown_source, "markdown"
+
+    return rendered_description, None
+
+
 class RawData:
     """Holds raw data for a test result."""
 
@@ -197,6 +214,7 @@ class TestResult(Result):
     inputs: Optional[Dict[str, Union[List[VMInput], VMInput]]] = None
     metadata: Optional[Dict[str, Any]] = None
     _was_description_generated: bool = False
+    _description_source: Optional[str] = None
     _unsafe: bool = False
     _client_config_cache: Optional[Any] = None
     _is_scorer_result: bool = False
@@ -237,6 +255,7 @@ def __getattribute__(self, name):
                     self.description,
                     self._was_description_generated,
                 ) = description.get_description()
+                self._description_source = description.markdown_source
 
         return super().__getattribute__(name)
 
@@ -597,17 +616,23 @@ async def process_batch():
                 if self._was_description_generated
                 else DEFAULT_REVISION_NAME
             )
-
-            tasks.append(
-                update_metadata(
-                    content_id=(
-                        f"{content_id}::{revision_name}"
-                        if content_id
-                        else f"test_description:{self.result_id}::{revision_name}"
-                    ),
-                    text=self.description,
-                )
+            content_id_with_revision = (
+                f"{content_id}::{revision_name}"
+                if content_id
+                else f"test_description:{self.result_id}::{revision_name}"
+            )
+            description_text, text_format = _description_transport(
+                self.description,
+                self._description_source,
             )
+            metadata_kwargs = {
+                "content_id": content_id_with_revision,
+                "text": description_text,
+            }
+            if text_format is not None:
+                metadata_kwargs["text_format"] = text_format
+
+            tasks.append(update_metadata(**metadata_kwargs))
 
         return await asyncio.gather(*tasks)
 
@@ -717,6 +742,7 @@ class TextGenerationResult(Result):
     section_id: Optional[str] = None
     context: Optional[Dict[str, Any]] = None
     _was_description_generated: bool = False
+    _description_source: Optional[str] = None
     _client_config_cache: Optional[Any] = None
 
     def __post_init__(self):
@@ -853,9 +879,13 @@ async def log_async(
             else f"{resolved_content_id}::{revision_name}"
         )
 
+        description_text, _ = _description_transport(
+            self.description,
+            self._description_source,
+        )
         return await api_client.alog_text(
             content_id=resolved_content_id,
-            text=self.description,
+            text=description_text,
             section_id=resolved_section_id,
         )
 
diff --git a/validmind/vm_models/result/utils.py b/validmind/vm_models/result/utils.py
index 9dfbb90e2..78e65cae6 100644
--- a/validmind/vm_models/result/utils.py
+++ b/validmind/vm_models/result/utils.py
@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os
-from typing import TYPE_CHECKING, Dict, List, Union
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
 
 from jinja2 import Template
 
@@ -35,7 +35,12 @@ def get_result_template():
     return _result_template
 
 
-async def update_metadata(content_id: str, text: str, _json: Union[Dict, List] = None):
+async def update_metadata(
+    content_id: str,
+    text: str,
+    _json: Union[Dict, List] = None,
+    text_format: Optional[str] = None,
+):
     """Create or update a metadata object."""
     parts = content_id.split("::")
     content_id = parts[0]
@@ -46,7 +51,12 @@ async def update_metadata(content_id: str, text: str, _json: Union[Dict, List] =
 
     logger.debug(f"Updating metadata for `{content_id}`")
 
-    await api_client.alog_metadata(content_id, text, _json)
+    await api_client.alog_metadata(
+        content_id,
+        text,
+        _json,
+        text_format=text_format,
+    )
 
 
 def tables_to_html(tables: List["ResultTable"]) -> str:

From 2381d7a94f41ee62d4bb9faf7eca32cff2612c15 Mon Sep 17 00:00:00 2001
From: Steven Chand <stevenchand21@gmail.com>
Date: Thu, 20 Aug 2026 17:57:03 -0700
Subject: [PATCH 3/6] [SC-17911] Negotiate Markdown metadata support

---
 tests/test_api_client.py   | 95 ++++++++++++++++++++++++++++----------
 validmind/api_client.py    | 10 ++--
 validmind/client_config.py |  4 ++
 3 files changed, 81 insertions(+), 28 deletions(-)

diff --git a/tests/test_api_client.py b/tests/test_api_client.py
index 2d0a42bf8..57e506f92 100644
--- a/tests/test_api_client.py
+++ b/tests/test_api_client.py
@@ -75,13 +75,15 @@ def run_async(self, func, *args, **kwargs):
     @patch("requests.get")
     def test_init_successful(self, mock_requests_get):
         mock_data = {
-            "model": {"name": "test_model", "cuid": os.environ["VM_API_MODEL"]}
+            "model": {"name": "test_model", "cuid": os.environ["VM_API_MODEL"]},
+            "feature_flags": {"log_metadata_markdown": True},
         }
         mock_response = Mock(status_code=200, json=Mock(return_value=mock_data))
         mock_requests_get.return_value = mock_response
 
         success = api_client.init()
         self.assertIsNone(success)
+        self.assertTrue(api_client.client_config.supports_log_metadata_markdown())
 
         mock_requests_get.assert_called_once_with(
             url=f"{os.environ['VM_API_HOST']}/ping",
@@ -249,18 +251,20 @@ def test_log_metadata_with_section_id(self, mock_post: MagicMock):
         )
 
     @patch("aiohttp.ClientSession.post")
-    def test_result_update_metadata_sends_waf_safe_markdown(
-        self, mock_post: MagicMock
-    ):
+    def test_result_update_metadata_sends_waf_safe_markdown(self, mock_post: MagicMock):
         equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
         mock_post.return_value = MockAsyncResponse(200, json={"cuid": "abc1234"})
 
-        self.run_async(
-            update_metadata,
-            "test_description:equation::default",
-            equation,
-            text_format="markdown",
-        )
+        with patch.dict(
+            api_client.client_config.feature_flags,
+            {"log_metadata_markdown": True},
+        ):
+            self.run_async(
+                update_metadata,
+                "test_description:equation::default",
+                equation,
+                text_format="markdown",
+            )
 
         mock_post.assert_called_once_with(
             f"{os.environ['VM_API_HOST']}/log_metadata",
@@ -274,6 +278,35 @@ def test_result_update_metadata_sends_waf_safe_markdown(
         )
         self.assertNotIn("<script", mock_post.call_args.kwargs["data"])
 
+    @patch("aiohttp.ClientSession.post")
+    def test_result_update_metadata_falls_back_for_legacy_backend(
+        self, mock_post: MagicMock
+    ):
+        equation = r"$WOE = \ln\dfrac{\%\ of\ Events}{\%\ of\ Non-Events}$"
+        legacy_html = md_to_html(equation, mathml=True)
+        mock_post.return_value = MockAsyncResponse(200, json={"cuid": "abc1234"})
+
+        with patch.dict(api_client.client_config.feature_flags, {}, clear=True):
+            self.run_async(
+                update_metadata,
+                "test_description:equation::default",
+                equation,
+                text_format="markdown",
+            )
+
+        mock_post.assert_called_once_with(
+            f"{os.environ['VM_API_HOST']}/log_metadata",
+            data=json.dumps(
+                {
+                    "content_id": "test_description:equation::default",
+                    "text": legacy_html,
+                }
+            ),
+        )
+        request_body = mock_post.call_args.kwargs["data"]
+        self.assertIn("<script", request_body)
+        self.assertNotIn("text_format", request_body)
+
     @patch("aiohttp.ClientSession.post")
     def test_log_test_result(self, mock_post):
         result = {
@@ -313,11 +346,15 @@ def test_log_text_generates_text_and_logs_metadata(
             },
         )
 
-        api_client.log_text(
-            content_id="dataset_summary_text",
-            prompt="Summarize the dataset.",
-            context={"content_ids": ["train_dataset", "target_description_text"]},
-        )
+        with patch.dict(
+            api_client.client_config.feature_flags,
+            {"log_metadata_markdown": True},
+        ):
+            api_client.log_text(
+                content_id="dataset_summary_text",
+                prompt="Summarize the dataset.",
+                context={"content_ids": ["train_dataset", "target_description_text"]},
+            )
 
         mock_requests_post.assert_called_once_with(
             url=f"{os.environ['VM_API_HOST']}/ai/generate/qualitative_text_generation",
@@ -365,11 +402,15 @@ def test_log_text_logs_metadata_with_section_id(
             },
         )
 
-        api_client.log_text(
-            content_id="dataset_summary_text",
-            prompt="Summarize the dataset.",
-            section_id="intended_use",
-        )
+        with patch.dict(
+            api_client.client_config.feature_flags,
+            {"log_metadata_markdown": True},
+        ):
+            api_client.log_text(
+                content_id="dataset_summary_text",
+                prompt="Summarize the dataset.",
+                section_id="intended_use",
+            )
 
         mock_requests_post.assert_called_once_with(
             url=f"{os.environ['VM_API_HOST']}/ai/generate/qualitative_text_generation",
@@ -409,11 +450,15 @@ def test_log_text_sends_tex_as_waf_safe_markdown(self, mock_post: MagicMock):
             },
         )
 
-        self.run_async(
-            api_client.alog_text,
-            "text_woe_equation",
-            text=equation,
-        )
+        with patch.dict(
+            api_client.client_config.feature_flags,
+            {"log_metadata_markdown": True},
+        ):
+            self.run_async(
+                api_client.alog_text,
+                "text_woe_equation",
+                text=equation,
+            )
 
         mock_post.assert_called_once_with(
             f"{os.environ['VM_API_HOST']}/log_metadata",
diff --git a/validmind/api_client.py b/validmind/api_client.py
index 86dac67d8..69d6e43a8 100644
--- a/validmind/api_client.py
+++ b/validmind/api_client.py
@@ -598,9 +598,9 @@ async def alog_metadata(
         _json (dict, optional): Free-form key-value pairs to assign to the metadata. Defaults to None.
         section_id (str, optional): Section ID to append the text block to when the
             content ID does not already exist.
-        text_format (str, optional): Format of ``text``. New ``log_text`` calls use
-            ``markdown`` so conversion happens after the request passes through the
-            WAF. Omitted for backward-compatible HTML payloads.
+        text_format (str, optional): Format of ``text``. Markdown is sent as-is when
+            the backend advertises support so conversion happens after the request
+            passes through the WAF. Older backends receive locally converted HTML.
 
     Raises:
         Exception: If the API call fails.
@@ -608,6 +608,10 @@ async def alog_metadata(
     Returns:
         dict: The response from the API.
     """
+    if text_format == "markdown" and not client_config.supports_log_metadata_markdown():
+        text = md_to_html(text, mathml=True)
+        text_format = None
+
     metadata_dict = {"content_id": content_id}
     if text is not None:
         metadata_dict["text"] = text
diff --git a/validmind/client_config.py b/validmind/client_config.py
index 1d3742655..671874e83 100644
--- a/validmind/client_config.py
+++ b/validmind/client_config.py
@@ -39,6 +39,10 @@ def can_generate_llm_test_descriptions(self):
         """Returns True if the client can generate LLM-based test descriptions."""
         return self.feature_flags.get("llm_test_descriptions", True)
 
+    def supports_log_metadata_markdown(self):
+        """Return whether the backend converts Markdown logged as metadata."""
+        return self.feature_flags.get("log_metadata_markdown", False)
+
 
 client_config = ClientConfig(
     model=None,

From 2793dd3ee87e0be06eddd87f16f063753e5b1fce Mon Sep 17 00:00:00 2001
From: Steven Chand <stevenchand21@gmail.com>
Date: Fri, 21 Aug 2026 11:36:16 -0700
Subject: [PATCH 4/6] test: add Markdown and HTML logging regression notebook

---
 .../markdown_html_logging_regression.ipynb    | 332 ++++++++++++++++++
 1 file changed, 332 insertions(+)
 create mode 100644 notebooks/code_sharing/markdown_html_logging_regression.ipynb

diff --git a/notebooks/code_sharing/markdown_html_logging_regression.ipynb b/notebooks/code_sharing/markdown_html_logging_regression.ipynb
new file mode 100644
index 000000000..6a876424c
--- /dev/null
+++ b/notebooks/code_sharing/markdown_html_logging_regression.ipynb
@@ -0,0 +1,332 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "copyright-sc17911",
+   "metadata": {},
+   "source": [
+    "<!-- VALIDMIND COPYRIGHT -->\n",
+    "\n",
+    "<small>\n",
+    "\n",
+    "***\n",
+    "\n",
+    "Copyright © 2023-2026 ValidMind Inc. All rights reserved.<br>\n",
+    "Refer to [LICENSE](https://github.com/validmind/validmind-library/blob/main/LICENSE) for details.<br>\n",
+    "SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial</small>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Markdown and HTML logging regression (SC-17911)\n",
+    "\n",
+    "This notebook verifies the compatibility contract for `log_text()` and `/tracking/log_metadata` after the WAF-safe TeX change. It covers plain Markdown, inline and display TeX, Markdown extensions, mixed Markdown/HTML, explicit HTML, and explicit MathJax HTML.\n",
+    "\n",
+    "The first two test matrices are deterministic and do not require credentials or a running backend:\n",
+    "\n",
+    "- When the backend advertises `log_metadata_markdown`, Markdown remains raw on the wire and carries `text_format=\"markdown\"`. The SDK does not put generated MathJax `<script>` tags in the request.\n",
+    "- When the capability is absent, the SDK preserves compatibility with older backends by converting Markdown locally and omitting `text_format`.\n",
+    "- Explicit caller-supplied HTML remains unchanged in both modes. This intentionally includes explicit `<script>` input; the WAF-safe change only prevents the SDK from generating script tags from Markdown before transport.\n",
+    "\n",
+    "The final section is an opt-in end-to-end check against a real backend. Set `VM_RUN_E2E=1` and the usual `VM_API_HOST`, `VM_API_KEY`, `VM_API_SECRET`, and `VM_API_MODEL` variables before executing the notebook. The E2E check creates or updates `test_description:sc17911_notebook_*` metadata records."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports-and-cases",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "import os\n",
+    "from unittest.mock import patch\n",
+    "\n",
+    "import pandas as pd\n",
+    "from bs4 import BeautifulSoup\n",
+    "\n",
+    "import validmind as vm\n",
+    "import validmind.api_client as api_client\n",
+    "from validmind.client_config import client_config\n",
+    "from validmind.utils import is_html, md_to_html\n",
+    "\n",
+    "CASES = [\n",
+    "    {\n",
+    "        \"name\": \"plain_markdown\",\n",
+    "        \"text\": \"## Compatibility heading\\n\\nA **bold** paragraph and a list:\\n\\n- one\\n- two\",\n",
+    "    },\n",
+    "    {\n",
+    "        \"name\": \"inline_tex\",\n",
+    "        \"text\": r\"Weight of Evidence is $WOE = \\ln\\dfrac{\\%\\ of\\ Events}{\\%\\ of\\ Non-Events}$.\",\n",
+    "    },\n",
+    "    {\n",
+    "        \"name\": \"display_tex\",\n",
+    "        \"text\": \"## Equation\\n\\n\" + r\"$$G(x) = \\sum_{i=1}^{n} w_i x_i$$\",\n",
+    "    },\n",
+    "    {\n",
+    "        \"name\": \"markdown_extensions\",\n",
+    "        \"text\": \"~~Deprecated~~ current value.[^1]\\n\\n| Metric | Value |\\n| --- | ---: |\\n| AUC | 0.91 |\\n\\n[^1]: Regression footnote.\",\n",
+    "    },\n",
+    "    {\n",
+    "        \"name\": \"mixed_markdown_html\",\n",
+    "        \"text\": \"## Mixed input\\n\\nMarkdown before an <em>inline HTML fragment</em>.\",\n",
+    "    },\n",
+    "    {\n",
+    "        \"name\": \"explicit_html\",\n",
+    "        \"text\": \"<h2>Explicit HTML</h2><p><strong>Keep this markup unchanged.</strong></p>\",\n",
+    "    },\n",
+    "    {\n",
+    "        \"name\": \"explicit_mathjax_html\",\n",
+    "        \"text\": r'<p><script type=\"math/tex\">WOE = \\ln\\dfrac{\\%\\ of\\ Events}{\\%\\ of\\ Non-Events}</script></p>',\n",
+    "    },\n",
+    "]\n",
+    "\n",
+    "assert {is_html(case[\"text\"]) for case in CASES} == {False, True}\n",
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        \"case\": [case[\"name\"] for case in CASES],\n",
+    "        \"detected_as\": [\"html\" if is_html(case[\"text\"]) else \"markdown\" for case in CASES],\n",
+    "    }\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "capture-helper",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "async def capture_log_text_request(case, supports_markdown):\n",
+    "    \"\"\"Run alog_text while capturing the serialized log_metadata body.\"\"\"\n",
+    "    captured = {}\n",
+    "\n",
+    "    async def capture_post(path, params=None, data=None, **kwargs):\n",
+    "        captured[\"path\"] = path\n",
+    "        captured[\"params\"] = params\n",
+    "        captured[\"body\"] = json.loads(data)\n",
+    "        return {\"content_id\": captured[\"body\"][\"content_id\"], \"text\": captured[\"body\"].get(\"text\")}\n",
+    "\n",
+    "    original_flags = client_config.feature_flags\n",
+    "    try:\n",
+    "        client_config.feature_flags = {\"log_metadata_markdown\": supports_markdown}\n",
+    "        with patch.object(api_client, \"_post\", new=capture_post):\n",
+    "            await api_client.alog_text(\n",
+    "                content_id=f'test_description:sc17911_{case[\"name\"]}',\n",
+    "                text=case[\"text\"],\n",
+    "            )\n",
+    "    finally:\n",
+    "        client_config.feature_flags = original_flags\n",
+    "\n",
+    "    assert captured[\"path\"] == \"log_metadata\"\n",
+    "    return captured[\"body\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "new-backend-heading",
+   "metadata": {},
+   "source": [
+    "## New backend: WAF-safe Markdown transport\n",
+    "\n",
+    "Markdown and TeX must stay raw in the request. Fully formed HTML must retain the legacy pass-through behavior."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "new-backend-matrix",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "new_backend_rows = []\n",
+    "for case in CASES:\n",
+    "    body = await capture_log_text_request(case, supports_markdown=True)\n",
+    "    html_input = is_html(case[\"text\"])\n",
+    "\n",
+    "    assert body[\"text\"] == case[\"text\"]\n",
+    "    if html_input:\n",
+    "        assert \"text_format\" not in body\n",
+    "    else:\n",
+    "        assert body[\"text_format\"] == \"markdown\"\n",
+    "        assert \"<script\" not in body[\"text\"].lower()\n",
+    "\n",
+    "    new_backend_rows.append(\n",
+    "        {\n",
+    "            \"case\": case[\"name\"],\n",
+    "            \"text_format\": body.get(\"text_format\", \"omitted\"),\n",
+    "            \"unchanged_on_wire\": body[\"text\"] == case[\"text\"],\n",
+    "            \"script_on_wire\": \"<script\" in body[\"text\"].lower(),\n",
+    "        }\n",
+    "    )\n",
+    "\n",
+    "pd.DataFrame(new_backend_rows)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "legacy-backend-heading",
+   "metadata": {},
+   "source": [
+    "## Older backend: compatibility fallback\n",
+    "\n",
+    "When the backend does not advertise support, Markdown must be converted locally and `text_format` must be omitted. Explicit HTML still passes through unchanged. This avoids silently storing raw Markdown on older customer-managed backends."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "legacy-backend-matrix",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "legacy_backend_rows = []\n",
+    "for case in CASES:\n",
+    "    body = await capture_log_text_request(case, supports_markdown=False)\n",
+    "    html_input = is_html(case[\"text\"])\n",
+    "    expected_text = case[\"text\"] if html_input else md_to_html(case[\"text\"], mathml=True)\n",
+    "\n",
+    "    assert \"text_format\" not in body\n",
+    "    assert body[\"text\"] == expected_text\n",
+    "\n",
+    "    legacy_backend_rows.append(\n",
+    "        {\n",
+    "            \"case\": case[\"name\"],\n",
+    "            \"converted_locally\": not html_input,\n",
+    "            \"matches_legacy_output\": body[\"text\"] == expected_text,\n",
+    "            \"script_on_wire\": \"<script\" in body[\"text\"].lower(),\n",
+    "        }\n",
+    "    )\n",
+    "\n",
+    "pd.DataFrame(legacy_backend_rows)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e2e-heading",
+   "metadata": {},
+   "source": [
+    "## Optional end-to-end backend check\n",
+    "\n",
+    "Run this section with `VM_RUN_E2E=1` to initialize the SDK from `VM_API_*`, log every case to the selected model's documentation, and verify the backend persists semantically equivalent rendered HTML while preserving explicit HTML byte-for-byte. The backend must advertise `feature_flags.log_metadata_markdown=true` for this check."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e2e-check",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "run_e2e = os.getenv(\"VM_RUN_E2E\", \"0\").lower() in {\"1\", \"true\", \"yes\"}\n",
+    "e2e_rows = []\n",
+    "\n",
+    "def assert_backend_render(case, stored_text):\n",
+    "    \"\"\"Assert stable rendering semantics without requiring byte-identical HTML.\"\"\"\n",
+    "    if is_html(case[\"text\"]):\n",
+    "        assert stored_text == case[\"text\"]\n",
+    "        return\n",
+    "\n",
+    "    assert stored_text != case[\"text\"]\n",
+    "    soup = BeautifulSoup(stored_text, \"html.parser\")\n",
+    "    name = case[\"name\"]\n",
+    "\n",
+    "    if name == \"plain_markdown\":\n",
+    "        assert soup.find(\"h2\").get_text(strip=True) == \"Compatibility heading\"\n",
+    "        assert soup.find(\"strong\").get_text(strip=True) == \"bold\"\n",
+    "        assert [item.get_text(strip=True) for item in soup.find_all(\"li\")] == [\"one\", \"two\"]\n",
+    "    elif name == \"inline_tex\":\n",
+    "        script = soup.find(\"script\", attrs={\"type\": \"math/tex\"})\n",
+    "        assert script is not None and \"WOE\" in script.get_text()\n",
+    "    elif name == \"display_tex\":\n",
+    "        script = soup.find(\"script\", attrs={\"type\": \"math/tex\"})\n",
+    "        assert script is not None and \"block\" in script.get(\"class\", [])\n",
+    "        assert \"G(x)\" in script.get_text()\n",
+    "    elif name == \"markdown_extensions\":\n",
+    "        assert soup.find(\"del\").get_text(strip=True) == \"Deprecated\"\n",
+    "        assert soup.select_one(\"figure.table table\") is not None\n",
+    "        assert soup.select_one(\"section.footnotes\") is not None\n",
+    "        assert [cell.get_text(strip=True) for cell in soup.find_all(\"th\")] == [\"Metric\", \"Value\"]\n",
+    "    elif name == \"mixed_markdown_html\":\n",
+    "        assert soup.find(\"h2\").get_text(strip=True) == \"Mixed input\"\n",
+    "        assert soup.find(\"em\") is None\n",
+    "        assert \"&lt;em&gt;inline HTML fragment&lt;/em&gt;\" in stored_text\n",
+    "    else:\n",
+    "        raise AssertionError(f\"Missing Markdown assertion for {name}\")\n",
+    "\n",
+    "if run_e2e:\n",
+    "    required = [\"VM_API_HOST\", \"VM_API_KEY\", \"VM_API_SECRET\", \"VM_API_MODEL\"]\n",
+    "    missing = [name for name in required if not os.getenv(name)]\n",
+    "    assert not missing, f\"Missing required environment variables: {missing}\"\n",
+    "\n",
+    "    vm.init(document=\"documentation\")\n",
+    "    assert client_config.supports_log_metadata_markdown(), (\n",
+    "        \"The connected backend must advertise log_metadata_markdown=true \"\n",
+    "        \"for the end-to-end portion of this regression.\"\n",
+    "    )\n",
+    "\n",
+    "    for case in CASES:\n",
+    "        response = await api_client.alog_text(\n",
+    "            content_id=f'test_description:sc17911_notebook_{case[\"name\"]}',\n",
+    "            text=case[\"text\"],\n",
+    "        )\n",
+    "        stored_text = response[\"text\"]\n",
+    "        assert_backend_render(case, stored_text)\n",
+    "\n",
+    "        e2e_rows.append(\n",
+    "            {\n",
+    "                \"case\": case[\"name\"],\n",
+    "                \"content_id\": response[\"content_id\"],\n",
+    "                \"persisted_as_expected\": True,\n",
+    "            }\n",
+    "        )\n",
+    "\n",
+    "    await api_client._get_session().close()\n",
+    "else:\n",
+    "    e2e_rows.append(\n",
+    "        {\n",
+    "            \"case\": \"skipped\",\n",
+    "            \"content_id\": \"Set VM_RUN_E2E=1 to run against a backend\",\n",
+    "            \"persisted_as_expected\": None,\n",
+    "        }\n",
+    "    )\n",
+    "\n",
+    "pd.DataFrame(e2e_rows)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "execution-notes",
+   "metadata": {},
+   "source": [
+    "## Headless execution\n",
+    "\n",
+    "Run the deterministic transport regression from the repository root:\n",
+    "\n",
+    "```bash\n",
+    "uv run jupyter nbconvert --execute --to notebook \\\n",
+    "  --output /tmp/markdown_html_logging_regression.out.ipynb \\\n",
+    "  notebooks/code_sharing/markdown_html_logging_regression.ipynb\n",
+    "```\n",
+    "\n",
+    "Add `VM_RUN_E2E=1` and valid `VM_API_*` variables to the command environment to include the backend check. A failed assertion makes notebook execution exit non-zero."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

From 788dafbacc15d7196bdcd4cf4557e5408ad23fd7 Mon Sep 17 00:00:00 2001
From: Steven Chand <stevenchand21@gmail.com>
Date: Fri, 21 Aug 2026 11:37:35 -0700
Subject: [PATCH 5/6] test: run logging notebook against either capability mode

---
 .../markdown_html_logging_regression.ipynb        | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/notebooks/code_sharing/markdown_html_logging_regression.ipynb b/notebooks/code_sharing/markdown_html_logging_regression.ipynb
index 6a876424c..abed98d76 100644
--- a/notebooks/code_sharing/markdown_html_logging_regression.ipynb
+++ b/notebooks/code_sharing/markdown_html_logging_regression.ipynb
@@ -211,7 +211,7 @@
    "source": [
     "## Optional end-to-end backend check\n",
     "\n",
-    "Run this section with `VM_RUN_E2E=1` to initialize the SDK from `VM_API_*`, log every case to the selected model's documentation, and verify the backend persists semantically equivalent rendered HTML while preserving explicit HTML byte-for-byte. The backend must advertise `feature_flags.log_metadata_markdown=true` for this check."
+    "Run this section with `VM_RUN_E2E=1` to initialize the SDK from `VM_API_*`, log every case to the selected model's documentation, and verify the backend persists semantically equivalent rendered HTML while preserving explicit HTML byte-for-byte. It runs in either capability state and reports whether it exercised backend Markdown conversion or the legacy SDK fallback."
    ]
   },
   {
@@ -243,8 +243,7 @@
     "        assert script is not None and \"WOE\" in script.get_text()\n",
     "    elif name == \"display_tex\":\n",
     "        script = soup.find(\"script\", attrs={\"type\": \"math/tex\"})\n",
-    "        assert script is not None and \"block\" in script.get(\"class\", [])\n",
-    "        assert \"G(x)\" in script.get_text()\n",
+    "        assert script is not None and \"G(x)\" in script.get_text()\n",
     "    elif name == \"markdown_extensions\":\n",
     "        assert soup.find(\"del\").get_text(strip=True) == \"Deprecated\"\n",
     "        assert soup.select_one(\"figure.table table\") is not None\n",
@@ -263,9 +262,11 @@
     "    assert not missing, f\"Missing required environment variables: {missing}\"\n",
     "\n",
     "    vm.init(document=\"documentation\")\n",
-    "    assert client_config.supports_log_metadata_markdown(), (\n",
-    "        \"The connected backend must advertise log_metadata_markdown=true \"\n",
-    "        \"for the end-to-end portion of this regression.\"\n",
+    "    markdown_capability = client_config.supports_log_metadata_markdown()\n",
+    "    transport_mode = (\n",
+    "        \"backend Markdown conversion\"\n",
+    "        if markdown_capability\n",
+    "        else \"legacy SDK conversion\"\n",
     "    )\n",
     "\n",
     "    for case in CASES:\n",
@@ -280,6 +281,7 @@
     "            {\n",
     "                \"case\": case[\"name\"],\n",
     "                \"content_id\": response[\"content_id\"],\n",
+    "                \"transport_mode\": transport_mode,\n",
     "                \"persisted_as_expected\": True,\n",
     "            }\n",
     "        )\n",
@@ -290,6 +292,7 @@
     "        {\n",
     "            \"case\": \"skipped\",\n",
     "            \"content_id\": \"Set VM_RUN_E2E=1 to run against a backend\",\n",
+    "            \"transport_mode\": None,\n",
     "            \"persisted_as_expected\": None,\n",
     "        }\n",
     "    )\n",

From f24ed2947b28cdfb689f747f03054a151d19dd4b Mon Sep 17 00:00:00 2001
From: Steven Chand <stevenchand21@gmail.com>
Date: Fri, 21 Aug 2026 11:52:15 -0700
Subject: [PATCH 6/6] docs: show client initialization in regression notebook

---
 .../markdown_html_logging_regression.ipynb    | 41 ++++++++++++++++---
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/notebooks/code_sharing/markdown_html_logging_regression.ipynb b/notebooks/code_sharing/markdown_html_logging_regression.ipynb
index abed98d76..ed0b230b5 100644
--- a/notebooks/code_sharing/markdown_html_logging_regression.ipynb
+++ b/notebooks/code_sharing/markdown_html_logging_regression.ipynb
@@ -214,14 +214,48 @@
     "Run this section with `VM_RUN_E2E=1` to initialize the SDK from `VM_API_*`, log every case to the selected model's documentation, and verify the backend persists semantically equivalent rendered HTML while preserving explicit HTML byte-for-byte. It runs in either capability state and reports whether it exercised backend Markdown conversion or the legacy SDK fallback."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "initialize-client-heading",
+   "metadata": {},
+   "source": [
+    "### Initialize the ValidMind client\n",
+    "\n",
+    "The client is initialized only for the optional end-to-end run. Credentials are read from environment variables and are never stored in the notebook."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "e2e-check",
+   "id": "initialize-client",
    "metadata": {},
    "outputs": [],
    "source": [
     "run_e2e = os.getenv(\"VM_RUN_E2E\", \"0\").lower() in {\"1\", \"true\", \"yes\"}\n",
+    "\n",
+    "if run_e2e:\n",
+    "    required = [\"VM_API_HOST\", \"VM_API_KEY\", \"VM_API_SECRET\", \"VM_API_MODEL\"]\n",
+    "    missing = [name for name in required if not os.getenv(name)]\n",
+    "    assert not missing, f\"Missing required environment variables: {missing}\"\n",
+    "\n",
+    "    vm.init(\n",
+    "        api_host=os.environ[\"VM_API_HOST\"],\n",
+    "        api_key=os.environ[\"VM_API_KEY\"],\n",
+    "        api_secret=os.environ[\"VM_API_SECRET\"],\n",
+    "        model=os.environ[\"VM_API_MODEL\"],\n",
+    "        document=\"documentation\",\n",
+    "    )\n",
+    "else:\n",
+    "    print(\"Client initialization skipped. Set VM_RUN_E2E=1 to enable it.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e2e-check",
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "e2e_rows = []\n",
     "\n",
     "def assert_backend_render(case, stored_text):\n",
@@ -257,11 +291,6 @@
     "        raise AssertionError(f\"Missing Markdown assertion for {name}\")\n",
     "\n",
     "if run_e2e:\n",
-    "    required = [\"VM_API_HOST\", \"VM_API_KEY\", \"VM_API_SECRET\", \"VM_API_MODEL\"]\n",
-    "    missing = [name for name in required if not os.getenv(name)]\n",
-    "    assert not missing, f\"Missing required environment variables: {missing}\"\n",
-    "\n",
-    "    vm.init(document=\"documentation\")\n",
     "    markdown_capability = client_config.supports_log_metadata_markdown()\n",
     "    transport_mode = (\n",
     "        \"backend Markdown conversion\"\n",