syntaxmatrix 2.6.4.4__py3-none-any.whl → 3.0.0__py3-none-any.whl

syntaxmatrix/__init__.py

@@ -20,8 +20,8 @@ error = _app_instance.error
 success = _app_instance.success
 info = _app_instance.info
 warning = _app_instance.warning
-# plt_plot = _app_instance.plt_plot
-# plotly_plot = _app_instance.plotly_plot
+plt_plot = _app_instance.plt_plot
+plotly_plot = _app_instance.plotly_plot
 
 set_user_icon = _app_instance.set_user_icon
 set_bot_icon = _app_instance.set_bot_icon
@@ -53,12 +53,14 @@ stream_process_query= _app_instance.stream_process_query
 process_query_stream = _app_instance.process_query_stream
 process_query = _app_instance.process_query
 embed_query = _app_instance.embed_query
-enable_user_files = _app_instance.enable_user_files
-enable_registration = _app_instance.enable_registration
 stream_write = _app_instance.stream_write
 enable_stream = _app_instance.enable_stream
 stream = _app_instance.stream
 get_stream_args = _app_instance.get_stream_args
+enable_user_files = _app_instance.enable_user_files
+enable_registration = _app_instance.enable_registration
+enable_site_documentation = _app_instance.enable_site_documentation
+enable_ml_lab = _app_instance.enable_ml_lab
 
 
 app = _app_instance.app

syntaxmatrix/agentic/agents.py

@@ -21,6 +21,7 @@ from dataclasses import dataclass
 import hashlib
 from PIL import Image
 from syntaxmatrix.page_layout_contract import normalise_layout, validate_layout
+from syntaxmatrix.page_builder_generation import compile_layout_to_html
 
 
 def token_calculator(total_input_content, llm_profile):
@@ -596,6 +597,7 @@ def classify_ml_job_agent(refined_question, dataset_profile):
 def agentic_generate_page(*,
     page_slug: str,
     website_description: str,
+    page_instructions: str = "",
     client_dir: str,
     pixabay_api_key: str = "",
     llm_profile: dict | None = None,
@@ -707,6 +709,22 @@ def agentic_generate_page(*,
         
         llm_profile = _prof.get_profile('coder')
         llm_profile['client'] = _prof.get_client(llm_profile)
+
+        # OpenAI JSON mode requirement:
+        # If we request text.format={type:"json_object"} (or response_format json_object),
+        # OpenAI will error unless the word "JSON" appears somewhere in the prompt context.
+        def _ensure_json_mode_prompts(sp: str, up: str):
+            sp = sp or ""
+            up = up or ""
+            hint = "\n\nReturn ONLY valid JSON. Do not include markdown. JSON only."
+            if "json" not in sp.lower():
+                sp = sp + hint
+            if "json" not in up.lower():
+                up = up + "\n\nRespond in JSON."
+            return sp, up
+
+        system_prompt, user_prompt = _ensure_json_mode_prompts(system_prompt, user_prompt)
+
         client = llm_profile["client"]
         model = llm_profile["model"]
         provider = llm_profile["provider"].lower()
@@ -806,11 +824,13 @@ def agentic_generate_page(*,
                 if not m:
                     raise RuntimeError(f"Model did not return JSON. Output was:\n{txt[:800]}")
                 return json.loads(m.group(0))
-        
+            
+        html = compile_layout_to_html(plan, page_slug=page_slug)
+
         return openai_sdk_response()
 
 
-    def _page_plan_system_prompt(spec: dict) -> str:
+    def _page_plan_system_prompt(spec: dict, page_instructions: str = "") -> str:
         allowed_sections = spec.get("allowed_section_types") or ["hero", "features", "gallery", "testimonials", "faq", "cta", "richtext"]
         req = spec.get("required_sections") or []
 
@@ -820,6 +840,11 @@ def agentic_generate_page(*,
                 [f"- {r['id']} (type: {r['type']})" for r in req]
             )
 
+        extra = ""
+        pi = (page_instructions or "").strip()
+        if pi:
+            extra = "\n\nPAGE-SPECIFIC INSTRUCTIONS (highest priority):\n" + pi + "\n"
+
         return f"""
         You are a senior UX designer + product copywriter for modern software websites.
 
@@ -834,6 +859,7 @@ def agentic_generate_page(*,
         - Choose icon names only from the allowed icon list.
         - Provide image search queries for items that need images. Keep queries on-topic (software/AI/tech).
 
+        {extra}
         {req_lines}
 
         OUTPUT:
@@ -887,7 +913,7 @@ def agentic_generate_page(*,
         """.strip()
 
 
-    def _make_page_plan(*, page_slug: str, website_description: str, template_spec: dict) -> dict:
+    def _make_page_plan(*, page_slug: str, website_description: str, template_spec: dict, page_instructions: str = "") -> dict:
         slug = _slugify(page_slug)
         wd = _strip(website_description)
         if not wd:
@@ -910,7 +936,7 @@ def agentic_generate_page(*,
         }, indent=2)
 
         plan = _get_json_call(
-            system_prompt=_page_plan_system_prompt(template_spec),
+            system_prompt=_page_plan_system_prompt(template_spec, page_instructions=page_instructions),
             user_prompt=user_prompt
         )
 
@@ -959,9 +985,10 @@ def agentic_generate_page(*,
             raise ValueError("Plan is too light on imagery; needs at least 4 items marked needsImage=true.")
 
 
-    def _repair_plan(*, plan: dict, error_msg: str, website_description: str) -> dict:
-        # Ask Gemini to repair the plan, not recreate randomly.
-        system_prompt = _page_plan_system_prompt() + "\n\nYou are repairing an existing plan. Keep it consistent and improve only what is needed."
+    def _repair_plan(*, plan: dict, error_msg: str, website_description: str, template_spec: dict, page_instructions: str = "") -> dict:
+        # Ask the model to repair the plan, not recreate randomly.
+        system_prompt = _page_plan_system_prompt(template_spec, page_instructions=page_instructions) + "\n\nYou are repairing an existing plan. Keep it consistent and improve only what is needed."
+
         user_prompt = json.dumps({
             "ERROR": error_msg,
             "WEBSITE_DESCRIPTION": website_description,
@@ -1023,6 +1050,88 @@ def agentic_generate_page(*,
         else:
             hero["items"] = [{"id": "hero_media", "type": "card", "title": "Hero image", "text": "", "imageUrl": img}]
 
+
+    def _ensure_gallery_section(plan: dict, template_spec: dict) -> None:
+        """
+        If we're generating a gallery page, guarantee at least one section has type="gallery"
+        so compile_layout_to_html activates the horizontal rail + arrows + lightbox.
+        """
+        try:
+            if (template_spec or {}).get("category") != "gallery":
+                return
+        except Exception:
+            return
+
+        secs = plan.get("sections")
+        if not isinstance(secs, list) or not secs:
+            return
+
+        def _stype(s):
+            return str((s or {}).get("type") or "").strip().lower()
+
+        # If already has a gallery section, we're done.
+        for s in secs:
+            if isinstance(s, dict) and _stype(s) == "gallery":
+                return
+
+        # Otherwise, convert the most image-heavy non-hero section into a gallery.
+        best = None
+        best_score = -1
+        for s in secs:
+            if not isinstance(s, dict):
+                continue
+            if _stype(s) == "hero":
+                continue
+            items = s.get("items") if isinstance(s.get("items"), list) else []
+            score = 0
+            for it in items:
+                if not isinstance(it, dict):
+                    continue
+                if it.get("needsImage") or it.get("imgQuery") or it.get("imageUrl"):
+                    score += 1
+            if score > best_score:
+                best_score = score
+                best = s
+
+        if best and best_score > 0:
+            best["type"] = "gallery"
+            best.setdefault("id", "sec_gallery")
+            if not str(best.get("title") or "").strip():
+                best["title"] = "Gallery"
+            if "cols" not in best:
+                best["cols"] = 3
+            return
+
+        # If nothing suitable exists, insert a fresh gallery section after the hero.
+        new_sec = {
+            "id": "sec_gallery",
+            "type": "gallery",
+            "title": "Gallery",
+            "text": "Browse highlights from the platform modules and UI surfaces.",
+            "cols": 3,
+            "items": [
+                {"id": "g1", "type": "card", "title": "Admin panel", "text": "Page Studio controls and content management.", "icon": "", "imgQuery": "admin panel dashboard ui", "needsImage": True},
+                {"id": "g2", "type": "card", "title": "Docs hub", "text": "Two-column documentation view with navigation.", "icon": "", "imgQuery": "documentation website sidebar layout", "needsImage": True},
+                {"id": "g3", "type": "card", "title": "ML lab", "text": "EDA and model results exported as reports.", "icon": "", "imgQuery": "machine learning dashboard analytics", "needsImage": True},
+                {"id": "g4", "type": "card", "title": "Chat assistant", "text": "Grounded answers with retrieval context.", "icon": "", "imgQuery": "chatbot interface web app", "needsImage": True},
+                {"id": "g5", "type": "card", "title": "Uploads", "text": "PDF and CSV ingestion workflows.", "icon": "", "imgQuery": "file upload web interface", "needsImage": True},
+                {"id": "g6", "type": "card", "title": "Deployment", "text": "Client instances, roles, and configuration.", "icon": "", "imgQuery": "cloud deployment dashboard", "needsImage": True},
+            ],
+        }
+
+        # Insert after hero if present; else prepend.
+        hero_idx = None
+        for i, s in enumerate(secs):
+            if isinstance(s, dict) and _stype(s) == "hero":
+                hero_idx = i
+                break
+
+        if hero_idx is None:
+            secs.insert(0, new_sec)
+        else:
+            secs.insert(hero_idx + 1, new_sec)
+
+
     TEMPLATE_SPECS = {
         "generic_v1": {
             "category": "landing",
@@ -1084,16 +1193,36 @@ def agentic_generate_page(*,
             "min_images": 6,
             "max_images": 9,
         },
+        "gallery_rail_v1": {
+            "category": "gallery",
+            "template": {"id": "gallery_rail_v1", "version": "1.0.0"},
+            "allowed_section_types": ["hero", "gallery", "testimonials", "faq", "cta", "richtext"],
+            "required_sections": [
+                {"id": "sec_hero", "type": "hero"},
+                {"id": "sec_gallery", "type": "gallery"},
+                {"id": "sec_cta", "type": "cta"},
+            ],
+            "min_sections": 3,
+            "max_sections": 6,
+            "min_images": 6,
+            "max_images": 9,
+        },
     }
 
     def _select_template_spec(slug: str) -> dict:
         s = _slugify(slug)
+
+        if any(k in s for k in ("gallery", "portfolio", "showcase", "screenshots", "photos")):
+            return TEMPLATE_SPECS["gallery_rail_v1"]
+
         if "service" in s:
             if any(k in s for k in ("pricing", "plan", "plans", "package", "packages", "tier", "tiers")):
                 return TEMPLATE_SPECS["services_detail_v1"]
             return TEMPLATE_SPECS["services_grid_v1"]
+
         if "about" in s:
             return TEMPLATE_SPECS["about_glass_hero_v1"]
+
         return TEMPLATE_SPECS["generic_v1"]
 
 
@@ -1134,7 +1263,16 @@ def agentic_generate_page(*,
         return r.content
 
 
-    def _save_image(img_bytes: bytes, out_path_no_ext: str, *, max_width: int = 1920) -> str:
+    def _save_image(
+        img_bytes: bytes,
+        out_path_no_ext: str,
+        *,
+        max_width: int = 1920,
+        thumb_out_path_no_ext: str | None = None,
+        thumb_max_w: int = 640,
+        thumb_max_h: int = 420,
+    ) -> tuple[str, str | None]:
+
         img = Image.open(io.BytesIO(img_bytes))
         img.load()
 
@@ -1154,7 +1292,26 @@ def agentic_generate_page(*,
         else:
             img.save(out_path, "PNG", optimize=True)
 
-        return out_path
+        thumb_path = None
+        if thumb_out_path_no_ext:
+            try:
+                # Create a thumbnail derived from the already-decoded image
+                t = img.copy()
+                t.thumbnail((int(thumb_max_w), int(thumb_max_h)))
+                t_has_alpha = ("A" in t.getbands())
+                t_ext = ".png" if t_has_alpha else ".jpg"
+                thumb_path = thumb_out_path_no_ext + t_ext
+                os.makedirs(os.path.dirname(thumb_path), exist_ok=True)
+
+                if t_ext == ".jpg":
+                    rgbt = t.convert("RGB") if t.mode != "RGB" else t
+                    rgbt.save(thumb_path, "JPEG", quality=80, optimize=True, progressive=True)
+                else:
+                    t.save(thumb_path, "PNG", optimize=True)
+            except Exception:
+                thumb_path = None
+
+        return out_path, thumb_path
 
 
     def _pick_pixabay_hit(hits: list[dict], *, min_width: int) -> dict | None:
@@ -1255,9 +1412,24 @@ def agentic_generate_page(*,
                         except Exception:
                             pass
 
-                    saved = _save_image(chosen_bytes, base, max_width=max_width)
+                    thumb_base = os.path.join(media_dir, "images", "thumbs", f"pixabay-{pid}")
+
+                    saved, thumb_saved = _save_image(
+                        chosen_bytes,
+                        base,
+                        max_width=max_width,
+                        thumb_out_path_no_ext=thumb_base,
+                        thumb_max_w=640,
+                        thumb_max_h=420,
+                    )
+
                     rel = os.path.relpath(saved, media_dir).replace("\\", "/")
                     it["imageUrl"] = f"/uploads/media/{rel}"
+
+                    if thumb_saved:
+                        trel = os.path.relpath(thumb_saved, media_dir).replace("\\", "/")
+                        it["thumbUrl"] = f"/uploads/media/{trel}"
+
                     downloads += 1
                 except Exception:
                     continue
@@ -1383,13 +1555,15 @@ def agentic_generate_page(*,
             #{page_id} .hero-panel{{
                 max-width:700px;
                 border:1px solid rgba(148,163,184,.30);
-                background:rgba(2,6,23,.24);
                 border-radius:var(--r);
                 padding:18px;
-                backdrop-filter: blur(4px);
                 -webkit-backdrop-filter: blur(4px);
                 box-shadow: 0 18px 40px rgba(2,6,23,.18);
                 color:#e2e8f0;
+                background:rgba(2,6,23,.13); /* more transparent */
+                backdrop-filter: blur(18px) saturate(155%);
+                -webkit-backdrop-filter: blur(18px) saturate(155%);
+
             }}
             #{page_id} .hero-panel p{{ color:rgba(226,232,240,.84); }}
             #{page_id} .hero-panel h1{{ text-shadow:0 10px 30px rgba(2,6,23,.45); }}
@@ -1610,8 +1784,13 @@ def agentic_generate_page(*,
     notes = []
 
     tpl_spec = _select_template_spec(page_slug)
-    plan = _make_page_plan(page_slug=page_slug, website_description=website_description, template_spec=tpl_spec)
+    plan = _make_page_plan(
+        page_slug=page_slug, 
+        website_description=website_description, 
+        template_spec=tpl_spec, page_instructions=page_instructions
+    )
 
+    _ensure_gallery_section(plan, tpl_spec)
 
     for attempt in range(max_retries + 1):
         try:
@@ -1621,7 +1800,8 @@ def agentic_generate_page(*,
             notes.append(f"plan_validation_failed: {e}")
             if attempt >= max_retries:
                 raise
-            plan = _repair_plan(plan=plan, error_msg=str(e), website_description=website_description)
+            plan = _repair_plan(plan=plan, error_msg=str(e), website_description=website_description, template_spec=tpl_spec, page_instructions=page_instructions)
+
 
     # Fill images locally (Pixabay) to avoid broken links
     if pixabay_api_key:
@@ -1659,7 +1839,7 @@ def agentic_generate_page(*,
     if _contains_placeholders(blob):
         raise RuntimeError("Refusing to publish: plan still contains placeholder-style text.")
 
-    html = compile_plan_to_html(plan)
+    html = compile_layout_to_html(plan, page_slug=page_slug)
     return {
         "slug": _slugify(plan.get("page") or page_slug),
         "plan": plan,

syntaxmatrix/agentic/agents_orchestrer.py

@@ -299,25 +299,31 @@ class OrchestrateMLSystem:
         REFINED ML TASKS & SPECS:
         {refined_tasks}
 
-        CONSTRAINTS:
+        ### CONSTRAINTS:
         - Assume 'df' is already loaded in the namespace. Do not use pd.read_csv.
         - Include all up-to-dateimports (pandas, numpy, sklearn, matplotlib, seaborn, etc.). 
         - Avoid any deprecated mehods, imports, statements.
-        - FIRST: Implement the 'Cold Start' cleaning and preprocessing logic (Check for nulls and impute based on column types in context).
+        - FIRST: Implement the 'Cold Start' cleaning (if not already done) and preprocessing logic (Check for nulls  and impute based on column types in context).
         - SECOND: (Modeling) Implement the ML pipeline (Split, Scale, Train, Predict).
         - THIRD: Implement the visualizations using the specific templates requested.
-        - Return ONLY the executable Python code. NO MARKDOWN (```), NO EXPLANATION.
-
-        PLOTS:
-        - Ensure that you display all the figures that you plotted nicely using plt.show.
-
-        TABLES:
-        - Use html tables for tabular data. 
+        - Return ONLY the executable Python code. NO MARKDOWN (```), NO EXPLANATION, NO PRELUDE, NO PREAMBLE.
+
+        ### Output rendering rules (STRICT)
+        - NEVER use: print(df.to_html()), DataFrame.to_html(), Styler.to_html(), or printing raw "<table>...</table>" strings.
+        - For any DataFrame (including classification reports, contingency tables, summary tables, head/tail/middle samples):
+        - Always render with:
+            from IPython.display import display
+            display(df)
+        - For styled tables you may use:
+            display(df.style)
+        but only if it improves readability (keep it simple).
+        - If you need text commentary, use print("...") ONLY for plain text. Do not print HTML.
+        Always import display when you intend to show DataFrames: from IPython.display import display
         """
         coder_profile = _prof.get_profile("coder")
         if not coder_profile:
             return "Error!: Set an appropriate coder profile"
-
+        
         thought, raw_code, usage = self._generate_ml_response(coder_profile ,system_prompt, user_prompt)
 
         # Robustly strip any potential markdown formatting

syntaxmatrix/client_docs.py

@@ -0,0 +1,237 @@
+# syntaxmatrix/client_docs.py
+from __future__ import annotations
+
+import os
+import re
+import html
+from dataclasses import dataclass
+from typing import List, Tuple
+
+from flask import abort, render_template
+from markupsafe import Markup
+
+
+@dataclass(frozen=True)
+class TocItem:
+    level: int
+    id: str
+    text: str
+
+
+_slug_rx = re.compile(r"[^a-z0-9\- ]+")
+_ws_rx = re.compile(r"\s+")
+
+
+def _slugify(text: str) -> str:
+    t = text.strip().lower()
+    t = _slug_rx.sub("", t)
+    t = _ws_rx.sub("-", t)
+    t = t.strip("-")
+    return t or "section"
+
+
+def _extract_headings(md: str) -> List[Tuple[int, str]]:
+    """
+    Extract ATX-style markdown headings (#, ##, ###, ...), ignoring fenced code blocks.
+    """
+    headings: List[Tuple[int, str]] = []
+    in_code = False
+    for line in md.splitlines():
+        if line.strip().startswith("```"):
+            in_code = not in_code
+            continue
+        if in_code:
+            continue
+
+        m = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
+        if not m:
+            continue
+        level = len(m.group(1))
+        title = m.group(2).strip()
+        # Avoid weird headings like "### ----"
+        if title and not all(ch in "-_=*" for ch in title):
+            headings.append((level, title))
+    return headings
+
+
+def _render_markdown_minimal(md: str, heading_ids: dict[str, str]) -> str:
+    """
+    Minimal markdown renderer (safe-by-default):
+    - headings, paragraphs, bullet lists, code fences, inline code, links, images
+    - everything else is HTML-escaped
+    """
+    lines = md.splitlines()
+    out: List[str] = []
+
+    in_code = False
+    code_lang = ""
+    code_buf: List[str] = []
+
+    in_ul = False
+
+    def flush_ul():
+        nonlocal in_ul
+        if in_ul:
+            out.append("</ul>")
+            in_ul = False
+
+    def flush_code():
+        nonlocal in_code, code_lang, code_buf
+        if not in_code:
+            return
+        code_text = "\n".join(code_buf)
+        out.append(
+            f'<pre class="smx-code"><code class="language-{html.escape(code_lang)}">'
+            f"{html.escape(code_text)}</code></pre>"
+        )
+        in_code = False
+        code_lang = ""
+        code_buf = []
+
+    def inline_fmt(s: str) -> str:
+        s = html.escape(s)
+
+        # inline code: `code`
+        s = re.sub(r"`([^`]+)`", lambda m: f"<code>{html.escape(m.group(1))}</code>", s)
+
+        # images: ![alt](url)
+        s = re.sub(
+            r"!\[([^\]]*)\]\(([^)]+)\)",
+            lambda m: f'<img alt="{html.escape(m.group(1))}" src="{html.escape(m.group(2))}" />',
+            s,
+        )
+
+        # links: [text](url)
+        s = re.sub(
+            r"\[([^\]]+)\]\(([^)]+)\)",
+            lambda m: f'<a href="{html.escape(m.group(2))}" target="_blank" rel="noopener noreferrer">{html.escape(m.group(1))}</a>',
+            s,
+        )
+
+        # bold **text**
+        s = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", s)
+
+        # italics *text* (simple)
+        s = re.sub(r"(?<!\*)\*([^*]+)\*(?!\*)", r"<em>\1</em>", s)
+
+        return s
+
+    # Pre-map heading text to stable IDs (supports duplicates)
+    # heading_ids is already built with de-duplication.
+    for raw in lines:
+        line = raw.rstrip("\n")
+
+        # fenced code blocks
+        m_code = re.match(r"^\s*```(\w+)?\s*$", line)
+        if m_code:
+            flush_ul()
+            if in_code:
+                flush_code()
+            else:
+                in_code = True
+                code_lang = (m_code.group(1) or "").strip()
+                code_buf = []
+            continue
+
+        if in_code:
+            code_buf.append(line)
+            continue
+
+        # headings
+        m_h = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
+        if m_h:
+            flush_ul()
+            level = len(m_h.group(1))
+            text = m_h.group(2).strip()
+            hid = heading_ids.get(text) or _slugify(text)
+            out.append(
+                f'<h{level} id="{html.escape(hid)}" class="smx-h">{inline_fmt(text)}</h{level}>'
+            )
+            continue
+
+        # bullet list items (supports "-" or "*")
+        m_li = re.match(r"^\s*[-*]\s+(.+)\s*$", line)
+        if m_li:
+            if not in_ul:
+                out.append("<ul>")
+                in_ul = True
+            out.append(f"<li>{inline_fmt(m_li.group(1).strip())}</li>")
+            continue
+
+        # blank line ends lists/paragraph chunks
+        if line.strip() == "":
+            flush_ul()
+            out.append("")
+            continue
+
+        # blockquote (single-line)
+        m_bq = re.match(r"^\s*>\s+(.+)\s*$", line)
+        if m_bq:
+            flush_ul()
+            out.append(f"<blockquote>{inline_fmt(m_bq.group(1).strip())}</blockquote>")
+            continue
+
+        # horizontal rule
+        if re.match(r"^\s*---\s*$", line):
+            flush_ul()
+            out.append("<hr/>")
+            continue
+
+        # normal paragraph line
+        flush_ul()
+        out.append(f"<p>{inline_fmt(line.strip())}</p>")
+
+    flush_ul()
+    flush_code()
+
+    return "\n".join(out)
+
+
+def build_docs_html_and_toc(md: str) -> Tuple[str, List[TocItem]]:
+    headings = _extract_headings(md)
+
+    # Build stable unique IDs
+    used: dict[str, int] = {}
+    heading_ids: dict[str, str] = {}
+
+    toc: List[TocItem] = []
+    for level, title in headings:
+        base = _slugify(title)
+        n = used.get(base, 0)
+        used[base] = n + 1
+        hid = base if n == 0 else f"{base}-{n+1}"
+
+        # map by raw title (good enough for this README)
+        # if duplicates exist with same title, only first maps here; duplicates are still in TOC correctly
+        if title not in heading_ids:
+            heading_ids[title] = hid
+
+        toc.append(TocItem(level=level, id=hid, text=title))
+
+    html_content = _render_markdown_minimal(md, heading_ids)
+    return html_content, toc
+
+
+def register_client_docs_routes(app, client_dir: str) -> None:
+    """
+    Call this once during app initialisation.
+    Exposes:
+      GET /docs
+    """
+    @app.get("/docs")
+    def smx_client_docs():
+        readme_path = os.path.join(client_dir, "README.md")
+        if not os.path.exists(readme_path):
+            abort(404, description="README.md not found in client root")
+
+        with open(readme_path, "r", encoding="utf-8") as f:
+            md = f.read()
+
+        docs_html, toc = build_docs_html_and_toc(md)
+
+        return render_template(
+            "client_docs.html",
+            page_title="System Documentation",
+            toc=toc,
+            docs_html=Markup(docs_html),
+        )