Add collapsable user guide in the UI

modified: requirements.txt
modified: ui/static/styles.css
modified: ui/templates/index.html
modified: ui_app.py

requirements.txt

@@ -9,3 +9,4 @@ tenacity
 flask
 gunicorn
 huggingface_hub
+markdown

ui/static/styles.css

@@ -34,6 +34,69 @@
       border-radius: 8px;
       padding: 16px;
     }
+    .guide-panel {
+      grid-column: 1 / -1;
+      padding: 0;
+      overflow: hidden;
+    }
+    .guide-panel details {
+      padding: 0;
+    }
+    .guide-panel summary {
+      display: flex;
+      justify-content: space-between;
+      gap: 12px;
+      align-items: center;
+      cursor: pointer;
+      padding: 14px 16px;
+      font-weight: 700;
+    }
+    .guide-panel summary small {
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 400;
+    }
+    .guide-content {
+      border-top: 1px solid var(--line);
+      padding: 16px;
+    }
+    .readme-content {
+      max-height: 520px;
+      overflow: auto;
+      font-size: 14px;
+      line-height: 1.55;
+    }
+    .guide-content h2 {
+      margin: 18px 0 8px;
+      font-size: 15px;
+    }
+    .guide-content h1 {
+      margin: 0 0 12px;
+      font-size: 20px;
+    }
+    .guide-content p {
+      margin: 0 0 10px;
+    }
+    .guide-content ul,
+    .guide-content ol {
+      margin: 0 0 12px;
+      padding-left: 20px;
+      color: var(--muted);
+    }
+    .guide-content li + li {
+      margin-top: 4px;
+    }
+    .guide-content code {
+      background: #eef2f7;
+      border-radius: 4px;
+      padding: 1px 4px;
+      color: var(--text);
+    }
+    .guide-content pre {
+      margin: 0;
+      white-space: pre-wrap;
+      color: var(--muted);
+    }
     label {
       display: block;
       margin: 14px 0 6px;
@@ -223,3 +286,12 @@
       border-top: 1px solid var(--line);
       margin: 18px 0;
     }
+    @media (max-width: 900px) {
+      main {
+        grid-template-columns: 1fr;
+      }
+      .guide-panel summary {
+        align-items: flex-start;
+        flex-direction: column;
+      }
+    }

ui/templates/index.html

@@ -12,6 +12,18 @@
     <h1>MasterMap Cleaner</h1>
   </header>
   <main>
+    <section class="guide-panel">
+      <details>
+        <summary>
+          <span>User Guide</span>
+          <small>Open README instructions</small>
+        </summary>
+        <div class="guide-content readme-content">
+          {{ readme_guide_html|safe }}
+        </div>
+      </details>
+    </section>
+
     <section>
       <h2>Dataset to Clean</h2>
       {% if clean_filename %}

ui_app.py

@@ -2,6 +2,7 @@ import os
 import secrets
 import sys
 import uuid
+from html import escape
 from pathlib import Path
 
 from flask import Flask, Response, jsonify, render_template, request, send_file, session
@@ -128,6 +129,26 @@ def default_models() -> str:
     return ",".join(env_preferred_models or PREFERRED_PRODUCTION_CHAT_MODELS)
 
 
+def read_readme_guide() -> str:
+    """Render README.md content for the in-app collapsible guide."""
+    readme_path = APP_ROOT / "README.md"
+    if not readme_path.is_file():
+        return "<p>User guide is not available.</p>"
+
+    text = readme_path.read_text(encoding="utf-8")
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) == 3:
+            text = parts[2].lstrip()
+
+    try:
+        import markdown
+    except ImportError:
+        return f"<pre>{escape(text)}</pre>"
+
+    return markdown.markdown(text, extensions=["extra", "sane_lists"])
+
+
 def render_page(message: str = "", error: str = ""):
     """Render the app with state scoped to the current browser session."""
     state = get_state()
@@ -142,6 +163,7 @@ def render_page(message: str = "", error: str = ""):
         **state,
         default_output_sheet=DEFAULT_OUTPUT_SHEET_NAME,
         default_models=default_models(),
+        readme_guide_html=read_readme_guide(),
         can_apply=can_apply_blueprint(),
         message=message,
         error=error,