Uploaded new Version of AgileAdvisor v0.5

# feat: AgileAdvisor v0.5 — Persistent Gist Sync, ScrumLens RAG, Auto-Tags, Duplicate Detection, Role Hierarchy & Quick-Feed

## Summary
This PR ships **AgileAdvisor v0.5**, a major feature drop that turns the static knowledge base into a living, self-improving RAG system. Every feed now auto-persists back to GitHub Gist, facts carry smart category tags, and a new **ScrumLens** mode lets users audit raw meeting transcripts against the vector memory.

---

## ✨ What's New

| Feature | Description |
|---|---|
| **🔄 Persistent Gist Sync** | Every feed—bulk or single-click—now appends to the GitHub Gist API and immediately hot-reloads the ChromaDB collection. The Gist is the single source of truth; local vector DB is just a fast mirror. |
| **🔍 ScrumLens Native RAG** | New **"ScrumLens 🔍"** tab. Paste any meeting transcript (Daily Standup, Retro, Planning) and the advisor cross-checks it against the KB, surfaces anti-patterns, assigns per-role action items, and gives a health score banner (🟢🟡🔴). |
| **⚠️ Duplicate Detection** | Live duplicate guard before you save. Uses exact match + `difflib.SequenceMatcher` (>88% similarity) + substring containment. The Feed tab now has a **"Preview Tags & Duplicates"** button that renders inline warnings. |
| **🏗️ Role Hierarchy Diagram** | New **"Role Hierarchy 🏗️"** tab. A pure HTML/CSS vertical flow diagram showing Stakeholders → PO → SM → Dev Team → RTE with color-coded borders and assigned output badges (e.g., Product Backlog, Impediment Removal, Potentially Shippable Increment). |
| **🏷️ Feed Data Auto-Tags** | Facts are auto-labelled on ingest via keyword heuristics (`ceremony`, `role`, `artifact`, `metric`, `anti-pattern`, `gamification`, `general`). Tags are embedded in Gist lines as `[ceremony] fact...` and stored in ChromaDB metadata for richer retrieval context. |
| **📦 Smart Quick-Feed Card** | After every answer in the **Ask** tab, a compact card appears showing the top retrieved fact + its tags. One **"➕ Feed This Fact to Dataset"** button instantly appends it to Gist without re-typing. |

---

## 🏗️ Technical Changes

- **`KnowledgeBase.auto_tag()`** — zero-token keyword heuristics for categorization.
- **`KnowledgeBase.check_duplicate()`** — exact / similar / contained tri-check.
- **`KnowledgeBase._parse_line()` / `_format_line()`** — round-trip serialization of `[tag] content` format in Gist.
- **`KnowledgeBase._append_lines_to_gist()`** — unified write path used by both bulk feed and quick feed.
- **`AgileAdvisor.analyze_transcript()`** — transcript audit pipeline with expanded context window (`n_results=3`).
- **ChromaDB metadata** — now stores `tags`, `hash`, and `source` per document.
- **Gradio UI** — 5 tabs: Ask, ScrumLens, Feed Dataset, Role Hierarchy, About.

---

## 🔄 Backwards Compatibility

- **Zero breaking changes.** Existing Gist lines without a `[tag]` prefix are gracefully parsed as `general`.
- The ChromaDB collection version metadata is bumped to `2.0` but re-initializes automatically on first run.

---

## 🧪 How to Test

1. **Ask a question** → verify the response still renders the Dataset Card + explanation + quote.
2. **Check Quick-Feed** → after the answer, click **"➕ Feed This Fact to Dataset"** and confirm the Gist grows by one tagged line.
3. **Open ScrumLens** → paste a fake Daily Standup transcript → verify you get a health score + red flags + role actions.
4. **Feed Dataset** → type two lines, one duplicate of an existing fact → click **Preview** → confirm the duplicate is flagged in red. Then click **Feed** and confirm Gist sync message.
5. **Role Hierarchy** → open the tab → verify the vertical flow diagram renders with correct role colors and output badges.
6. **Restart the Space** → confirm the KB reloads from Gist with tags intact (check the stats bar document count).

---

## 📁 Files Added

- `AgileAdvisor-v0.5.py`

---

## ✅ PR Checklist

- [x] Code runs locally without errors
- [x] Gist read/write tested with live token
- [x] ChromaDB persistent storage verified across restarts
- [x] No hardcoded secrets or API keys exposed
- [x] HTML output sanitized via `sanitize_html()`
- [x] Backwards compatible with untagged legacy Gist data

---

**Ready for review - `app.py`.** 🚀

AgileAdvisor-v0.5.py

@@ -0,0 +1,1312 @@
+import gradio as gr
+import chromadb
+from chromadb.utils import embedding_functions
+from groq import Groq
+import os
+import requests
+import json
+import hashlib
+import logging
+from typing import List, Optional, Tuple
+from dataclasses import dataclass, field
+import re
+import difflib
+
+# =========================
+# LOGGING SETUP (HF Spaces compatible)
+# =========================
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+# =========================
+# CONFIGURATION
+# =========================
+
+
+@dataclass
+class Config:
+    """Centralized configuration - optimized for Hugging Face Spaces"""
+
+    # GitHub Gist Config
+    GITHUB_USERNAME: str = "suryasticsai"
+    GIST_ID: str = "c25ec2898e91a2ce09ab74930741907e"
+    GIST_FILENAME: str = "agile-knowledge-base.txt"
+
+    # ChromaDB Config
+    COLLECTION_NAME: str = "agile_knowledge"
+    CHROMA_PERSIST_DIR: str = "./chroma_db"
+
+    # Limits
+    MAX_QUERY_LENGTH: int = 500
+    MAX_FEED_LENGTH: int = 10000
+    DEFAULT_N_RESULTS: int = 1
+
+    # Groq Config
+    GROQ_MODEL: str = "llama-3.1-8b-instant"
+    GROQ_TEMPERATURE: float = 0.4
+    GROQ_MAX_TOKENS: int = 1000
+
+    # API Timeouts
+    REQUEST_TIMEOUT: int = 10
+    GROQ_TIMEOUT: float = 60.0
+
+    # Auto-tagging categories
+    CATEGORIES: Tuple[str, ...] = (
+        "ceremony",
+        "role",
+        "artifact",
+        "metric",
+        "anti-pattern",
+        "gamification",
+        "general",
+    )
+
+    @property
+    def gist_url(self) -> str:
+        return f"https://gist.githubusercontent.com/{self.GITHUB_USERNAME}/{self.GIST_ID}/raw/{self.GIST_FILENAME}"
+
+    @property
+    def gist_api_url(self) -> str:
+        return f"https://api.github.com/gists/{self.GIST_ID}"
+
+
+CONFIG = Config()
+
+# =========================
+# KNOWLEDGE BASE MANAGER
+# =========================
+
+
+class KnowledgeBase:
+    """
+    Encapsulates ChromaDB + Gist operations.
+    Optimized for Hugging Face Spaces with persistent storage.
+    """
+
+    def __init__(self):
+        self.config = CONFIG
+
+        # Initialize ChromaDB with persistent storage
+        self.client = chromadb.PersistentClient(path=self.config.CHROMA_PERSIST_DIR)
+        self.emb = embedding_functions.DefaultEmbeddingFunction()
+        self.collection = self._init_collection()
+
+        # Initialize Groq client with proper timeout
+        groq_key = os.environ.get("GROQ_API_KEY")
+        if not groq_key:
+            logger.error("GROQ_API_KEY not found in environment/secrets!")
+            self.groq_client = None
+        else:
+            self.groq_client = Groq(
+                api_key=groq_key, timeout=self.config.GROQ_TIMEOUT, max_retries=2
+            )
+            logger.info("Groq client initialized")
+
+        # Load data from Gist or defaults
+        self._load_data()
+
+    def _init_collection(self):
+        """Get or create collection safely"""
+        try:
+            collection = self.client.get_or_create_collection(
+                name=self.config.COLLECTION_NAME,
+                embedding_function=self.emb,
+                metadata={
+                    "description": "Agile knowledge base for RAG",
+                    "version": "2.0",
+                    "source": "github_gist",
+                },
+            )
+            count = collection.count()
+            logger.info(f"Collection ready with {count} documents")
+            return collection
+        except Exception as e:
+            logger.error(f"Failed to initialize collection: {e}")
+            raise RuntimeError(f"ChromaDB init failed: {e}")
+
+    # --- Tagging & Parsing Helpers ---
+
+    def auto_tag(self, text: str) -> List[str]:
+        """Keyword-based auto-tagging without burning LLM tokens."""
+        text_lower = text.lower()
+        tags = set()
+        keyword_map = {
+            "ceremony": [
+                "sprint planning",
+                "daily standup",
+                "daily scrum",
+                "sprint review",
+                "sprint retrospective",
+                "retrospective",
+                "refinement",
+                "backlog grooming",
+                "review",
+                "planning",
+            ],
+            "role": [
+                "product owner",
+                "scrum master",
+                "dev team",
+                "developer",
+                "development team",
+                "stakeholder",
+                "rte",
+                "agile coach",
+                "scrum team",
+            ],
+            "artifact": [
+                "product backlog",
+                "sprint backlog",
+                "increment",
+                "definition of done",
+                "definition of ready",
+                "burndown",
+                "velocity",
+                "user story",
+                "epic",
+            ],
+            "metric": [
+                "velocity",
+                "burndown",
+                "lead time",
+                "cycle time",
+                "cfd",
+                "cumulative flow",
+                "throughput",
+                "wip",
+            ],
+            "anti-pattern": [
+                "anti-pattern",
+                "mistake",
+                "wrong",
+                "fail",
+                "smell",
+                "chaos",
+                "bad practice",
+                "should not",
+                "never",
+            ],
+            "gamification": [
+                "game",
+                "points",
+                "badge",
+                "leaderboard",
+                "reward",
+                "fun",
+                "motivation",
+                "kudos",
+                "competition",
+            ],
+        }
+        for tag, keywords in keyword_map.items():
+            if any(kw in text_lower for kw in keywords):
+                tags.add(tag)
+        if not tags:
+            tags.add("general")
+        return sorted(list(tags))
+
+    def _parse_line(self, line: str) -> Tuple[str, List[str]]:
+        """Parse a Gist line: [tag1,tag2] content..."""
+        line = line.strip()
+        if not line:
+            return "", []
+        m = re.match(r"^\[([a-zA-Z0-9_, -]+)\]\s*(.+)", line)
+        if m:
+            tags = [t.strip().lower() for t in m.group(1).split(",")]
+            return m.group(2).strip(), tags
+        return line, ["general"]
+
+    def _format_line(self, content: str, tags: List[str]) -> str:
+        """Serialize a fact with its primary tag(s) for Gist persistence."""
+        primary = [t for t in tags if t != "general"]
+        if primary:
+            return f"[{','.join(primary)}] {content}"
+        return content
+
+    def check_duplicate(
+        self, text: str
+    ) -> Tuple[bool, Optional[str], str]:
+        """Check if a fact already exists (exact, similar, or contained)."""
+        text_clean = text.strip().lower()
+        if not text_clean:
+            return False, None, ""
+        try:
+            existing = self.collection.get(include=["documents"])
+            docs = existing.get("documents", []) if existing else []
+            for doc in docs:
+                if not doc:
+                    continue
+                doc_clean = doc.strip().lower()
+                if text_clean == doc_clean:
+                    return True, doc, "exact"
+                ratio = difflib.SequenceMatcher(None, text_clean, doc_clean).ratio()
+                if ratio > 0.88:
+                    return True, doc, "similar"
+                if len(text_clean) > 25 and (
+                    text_clean in doc_clean or doc_clean in text_clean
+                ):
+                    return True, doc, "contained"
+            return False, None, ""
+        except Exception as e:
+            logger.error(f"Duplicate check failed: {e}")
+            return False, None, ""
+
+    def preview_feed(self, new_text: str) -> str:
+        """Live preview of tags & duplicates before feeding."""
+        if not new_text.strip():
+            return "<div style='color:#64748b;padding:12px;'>Type something to preview tags & duplicates...</div>"
+        lines = [l.strip() for l in new_text.split("\n") if l.strip()]
+        parts = []
+        for line in lines:
+            tags = self.auto_tag(line)
+            is_dup, matched, match_type = self.check_duplicate(line)
+            tag_badges = "".join(
+                [
+                    f'<span style="background:#1e293b;color:#00d4aa;padding:2px 8px;border-radius:4px;font-size:0.7rem;margin-right:4px;">{t}</span>'
+                    for t in tags
+                ]
+            )
+            dup_badge = ""
+            if is_dup:
+                dup_badge = f'<span style="background:rgba(239,68,68,0.15);color:#ef4444;padding:2px 8px;border-radius:4px;font-size:0.7rem;">⚠️ {match_type} duplicate</span>'
+            parts.append(
+                f"""
+                <div style="border-bottom:1px solid #1e293b;padding:8px 0;">
+                    <div style="color:#cbd5e1;font-size:0.85rem;margin-bottom:4px;">{line}</div>
+                    <div style="display:flex;gap:6px;align-items:center;flex-wrap:wrap;">
+                        {tag_badges} {dup_badge}
+                    </div>
+                </div>
+                """
+            )
+        return f'<div style="background:#0f172a;border:1px solid #1e293b;border-radius:8px;padding:12px;">{"".join(parts)}</div>'
+
+    # --- Loading ---
+
+    def _load_data(self):
+        """Load from Gist, fallback to defaults."""
+        try:
+            response = requests.get(
+                self.config.gist_url, timeout=self.config.REQUEST_TIMEOUT
+            )
+            response.raise_for_status()
+
+            lines = [line.strip() for line in response.text.split("\n") if line.strip()]
+            documents, tags_list = [], []
+            for line in lines:
+                content, tags = self._parse_line(line)
+                if content:
+                    documents.append(content)
+                    tags_list.append(tags)
+
+            if documents:
+                self._update_collection(documents, tags_list, replace=True)
+                logger.info(f"Loaded {len(documents)} documents from Gist")
+            else:
+                logger.warning("Gist empty, loading defaults")
+                self._load_defaults()
+
+        except Exception as e:
+            logger.warning(f"Could not load from Gist: {e}")
+            self._load_defaults()
+
+    def _load_defaults(self):
+        """Fallback Agile knowledge with tags."""
+        defaults = [
+            ("Sprint Planning is where the Scrum Team selects work from the Product Backlog for the upcoming Sprint", ["ceremony"]),
+            ("Daily Standup is a 15-minute time-boxed event for the Development Team to synchronize activities and plan for the next 24 hours", ["ceremony"]),
+            ("Sprint Review is held at the end of the Sprint to inspect the Increment and adapt the Product Backlog if needed", ["ceremony"]),
+            ("Sprint Retrospective is an opportunity for the Scrum Team to inspect itself and create a plan for improvements for the next Sprint", ["ceremony"]),
+            ("Product Owner is responsible for maximizing the value of the product resulting from work of the Development Team", ["role"]),
+            ("Scrum Master is responsible for promoting and supporting Scrum by helping everyone understand Scrum theory, practice, rules, and values", ["role"]),
+            ("Definition of Done is a shared understanding of what it means for work to be complete, ensuring transparency and quality", ["artifact"]),
+            ("Velocity is a measure of the amount of work a Team can tackle during a single Sprint, used for planning not performance measurement", ["metric"]),
+        ]
+        docs = [d[0] for d in defaults]
+        tags = [d[1] for d in defaults]
+        self._update_collection(docs, tags, replace=True)
+        logger.info(f"Loaded {len(defaults)} default documents")
+
+    def _update_collection(
+        self,
+        documents: List[str],
+        tags_list: Optional[List[List[str]]] = None,
+        replace: bool = False,
+    ):
+        """Safely update ChromaDB collection with metadata tags."""
+        try:
+            if replace:
+                try:
+                    existing = self.collection.get()
+                    if existing and existing.get("ids"):
+                        self.collection.delete(ids=existing["ids"])
+                        logger.info(f"Cleared {len(existing['ids'])} existing docs")
+                except Exception:
+                    pass
+
+            if documents:
+                metadatas = []
+                for i, doc in enumerate(documents):
+                    tags = (
+                        tags_list[i]
+                        if tags_list and i < len(tags_list)
+                        else ["general"]
+                    )
+                    metadatas.append(
+                        {
+                            "source": "gist",
+                            "index": i,
+                            "tags": ",".join(tags),
+                            "hash": hashlib.md5(doc.encode()).hexdigest(),
+                        }
+                    )
+                self.collection.add(
+                    documents=documents,
+                    ids=[
+                        f"doc_{hashlib.md5(doc.encode()).hexdigest()}"
+                        for doc in documents
+                    ],
+                    metadatas=metadatas,
+                )
+                logger.info(f"Added {len(documents)} documents")
+
+        except Exception as e:
+            logger.error(f"Failed to update collection: {e}")
+            raise
+
+    def query(self, question: str, n_results: int = None) -> Tuple[List[str], str]:
+        """Query knowledge base. Returns: (documents_list, formatted_context_string)"""
+        if not question or not question.strip():
+            return [], "No question provided."
+
+        n_results = n_results or self.config.DEFAULT_N_RESULTS
+
+        try:
+            available = self.collection.count()
+            n_results = min(n_results, available or 1)
+
+            results = self.collection.query(
+                query_texts=[question.strip()],
+                n_results=n_results,
+                include=["documents", "distances", "metadatas"],
+            )
+
+            documents = results.get("documents")
+            if not documents or not isinstance(documents, list) or len(documents) == 0:
+                return [], "No matching Agile knowledge found."
+
+            docs = documents[0]
+            if not docs:
+                return [], "No relevant documents found."
+
+            context_parts = []
+            distances = (
+                results.get("distances", [[]])[0] if results.get("distances") else [0.5] * len(docs)
+            )
+            metadatas = (
+                results.get("metadatas", [[]])[0] if results.get("metadatas") else [{}] * len(docs)
+            )
+
+            for i, (doc, dist, meta) in enumerate(zip(docs, distances, metadatas), 1):
+                relevance = "High" if dist < 0.3 else "Medium" if dist < 0.6 else "Low"
+                tags = meta.get("tags", "general")
+                context_parts.append(
+                    f"[Match {i}] (Relevance: {relevance} | Tags: {tags})\n{doc}"
+                )
+
+            return docs, "\n\n".join(context_parts)
+
+        except Exception as e:
+            logger.error(f"Query failed: {e}")
+            return [], f"Query error: {str(e)}"
+
+    # --- Gist Persistence ---
+
+    def _append_lines_to_gist(self, lines: List[str]) -> str:
+        """Core Gist append logic used by bulk feed & quick feed."""
+        if not lines:
+            return "Nothing to append."
+        token = os.environ.get("GITHUB_TOKEN")
+        if not token:
+            return "GITHUB_TOKEN not found! Add it in HF Spaces Settings > Secrets."
+
+        try:
+            headers = {
+                "Authorization": f"token {token}",
+                "Accept": "application/vnd.github.v3+json",
+            }
+
+            response = requests.get(
+                self.config.gist_api_url,
+                headers=headers,
+                timeout=self.config.REQUEST_TIMEOUT,
+            )
+            response.raise_for_status()
+
+            gist_data = response.json()
+            current_content = gist_data["files"][self.config.GIST_FILENAME]["content"]
+
+            existing_lines = set(
+                line.strip() for line in current_content.split("\n") if line.strip()
+            )
+            to_add = [line for line in lines if line.strip() not in existing_lines]
+
+            if not to_add:
+                return "✅ All facts already exist in the dataset. No duplicates added."
+
+            updated_content = current_content.rstrip() + "\n" + "\n".join(to_add)
+
+            payload = {
+                "files": {self.config.GIST_FILENAME: {"content": updated_content}}
+            }
+
+            update_resp = requests.patch(
+                self.config.gist_api_url,
+                headers=headers,
+                data=json.dumps(payload),
+                timeout=self.config.REQUEST_TIMEOUT,
+            )
+            update_resp.raise_for_status()
+
+            # Refresh ChromaDB from updated content
+            all_lines = [
+                line.strip() for line in updated_content.split("\n") if line.strip()
+            ]
+            documents, tags_list = [], []
+            for line in all_lines:
+                content, tags = self._parse_line(line)
+                if content:
+                    documents.append(content)
+                    tags_list.append(tags)
+
+            self._update_collection(documents, tags_list, replace=True)
+
+            return f"🚀 Success! Added {len(to_add)} new fact(s). Total: {len(documents)} documents."
+
+        except requests.RequestException as e:
+            logger.error(f"GitHub API error: {e}")
+            return f"GitHub API error: {str(e)}"
+        except Exception as e:
+            logger.error(f"Update failed: {e}")
+            return f"Error: {str(e)}"
+
+    def update_gist(self, new_text: str) -> str:
+        """Bulk update from Feed Dataset tab."""
+        if not new_text or not new_text.strip():
+            return "Empty input! Please provide some Agile knowledge to feed."
+        if len(new_text) > self.config.MAX_FEED_LENGTH:
+            return f"Too long! ({len(new_text)} chars). Max: {self.config.MAX_FEED_LENGTH}"
+
+        raw_lines = [l.strip() for l in new_text.split("\n") if l.strip()]
+        formatted = []
+        for line in raw_lines:
+            tags = self.auto_tag(line)
+            formatted.append(self._format_line(line, tags))
+
+        return self._append_lines_to_gist(formatted)
+
+    def feed_single_fact(self, text: str, tags_str: str) -> str:
+        """One-click feed from Ask advisor panel."""
+        if not text or not text.strip():
+            return "No fact to feed."
+        tags = [t.strip() for t in tags_str.split(",") if t.strip()]
+        if not tags:
+            tags = self.auto_tag(text)
+        formatted = self._format_line(text.strip(), tags)
+        return self._append_lines_to_gist([formatted])
+
+    def get_stats(self) -> dict:
+        """Get KB stats for UI display."""
+        try:
+            return {
+                "total_documents": self.collection.count(),
+                "collection_name": self.config.COLLECTION_NAME,
+                "storage": self.config.CHROMA_PERSIST_DIR,
+                "groq_ready": self.groq_client is not None,
+            }
+        except Exception as e:
+            return {"error": str(e)}
+
+
+# =========================
+# HTML SANITIZATION
+# =========================
+
+
+def sanitize_html(text: str) -> str:
+    """Prevent XSS - strip dangerous tags and attributes"""
+    if not text:
+        return ""
+    text = re.sub(
+        r"<script[^>]*>.*?</script>", "", text, flags=re.DOTALL | re.IGNORECASE
+    )
+    text = re.sub(r'\s*on\w+\s*=\s*["\'][^"\']*["\']', "", text, flags=re.IGNORECASE)
+    text = re.sub(r"javascript:", "", text, flags=re.IGNORECASE)
+    return text
+
+
+# =========================
+# SYSTEM PROMPTS
+# =========================
+
+SYSTEM_PROMPT = """
+You are Scrum Wizard — a sharp, witty, brutally honest Agile Coach with 10 years of SAFe experience.
+You cut through corporate fluff. You celebrate good Agile. You roast bad Agile with humor and love.
+
+CRITICAL RULES:
+- You ALWAYS respond in pure HTML only. No markdown. No plain text. No code fences.
+- ALWAYS show the DATASET FACT CARD first before any explanation.
+- If factual data exists in context, show it clearly and accurately.
+- Fill ALL template placeholders below. Never leave placeholders empty.
+
+Your response MUST follow this EXACT structure:
+
+<div style="font-family:sans-serif;max-width:800px;margin:0 auto;padding:8px">
+
+  <!-- DATASET CARD -->
+  <div style="background:linear-gradient(135deg,#052e16,#064e3b);border:1px solid rgba(16,185,129,0.25);border-left:5px solid #10b981;border-radius:14px;padding:18px 22px;margin-bottom:16px;box-shadow:0 0 0 1px rgba(16,185,129,0.05)">
+    <div style="display:flex;align-items:center;gap:10px;margin-bottom:10px">
+      <div style="width:34px;height:34px;border-radius:10px;background:rgba(16,185,129,0.15);display:flex;align-items:center;justify-content:center;font-size:1rem">📦</div>
+      <div>
+        <div style="font-size:0.72rem;color:#6ee7b7;font-weight:700;letter-spacing:2px;text-transform:uppercase">Data Retrieved From Dataset</div>
+        <div style="font-size:0.75rem;color:#86efac;margin-top:2px">Exact matched Agile knowledge retrieved from vector memory</div>
+      </div>
+    </div>
+    <div style="background:rgba(255,255,255,0.03);border:1px solid rgba(255,255,255,0.05);padding:16px 18px;border-radius:12px">
+      <div style="color:#ecfdf5;font-size:0.96rem;line-height:1.8;font-weight:500">{dataset_match}</div>
+    </div>
+  </div>
+
+  <!-- MAIN EXPLANATION CARD -->
+  <div style="background:linear-gradient(135deg,#1a1a2e,#16213e);border-left:4px solid #00d4aa;border-radius:12px;padding:20px 24px;margin-bottom:16px">
+    <div style="font-size:0.7rem;color:#00d4aa;font-weight:700;letter-spacing:2px;text-transform:uppercase;margin-bottom:8px">⚡ AgileAdvisor Says</div>
+    <div style="font-size:1.1rem;font-weight:700;color:#f1f5f9;margin-bottom:8px">{topic_title}</div>
+    <div style="color:#94a3b8;font-size:0.9rem;line-height:1.7">{explanation}</div>
+  </div>
+
+  <!-- KEY POINTS -->
+  <div style="background:#111827;border:1px solid #1e293b;border-radius:12px;padding:20px 24px;margin-bottom:16px">
+    <div style="font-size:0.7rem;color:#8b5cf6;font-weight:700;letter-spacing:2px;text-transform:uppercase;margin-bottom:14px">📖 What This Actually Means</div>
+    <div style="display:flex;flex-direction:column;gap:10px">
+      <div style="display:flex;gap:12px;align-items:flex-start">
+        <div style="background:#8b5cf6;color:#fff;border-radius:6px;padding:4px 10px;font-size:0.75rem;font-weight:700;white-space:nowrap;margin-top:2px">01</div>
+        <div style="color:#cbd5e1;font-size:0.88rem;line-height:1.6">{key_point_1}</div>
+      </div>
+      <div style="display:flex;gap:12px;align-items:flex-start">
+        <div style="background:#8b5cf6;color:#fff;border-radius:6px;padding:4px 10px;font-size:0.75rem;font-weight:700;white-space:nowrap;margin-top:2px">02</div>
+        <div style="color:#cbd5e1;font-size:0.88rem;line-height:1.6">{key_point_2}</div>
+      </div>
+      <div style="display:flex;gap:12px;align-items:flex-start">
+        <div style="background:#8b5cf6;color:#fff;border-radius:6px;padding:4px 10px;font-size:0.75rem;font-weight:700;white-space:nowrap;margin-top:2px">03</div>
+        <div style="color:#cbd5e1;font-size:0.88rem;line-height:1.6">{key_point_3}</div>
+      </div>
+    </div>
+  </div>
+
+  <!-- PEOPLE FLOW -->
+  <div style="background:#111827;border:1px solid #1e293b;border-radius:12px;padding:20px 24px;margin-bottom:16px">
+    <div style="font-size:0.7rem;color:#f59e0b;font-weight:700;letter-spacing:2px;text-transform:uppercase;margin-bottom:16px">👥 Who's Involved & In What Order</div>
+    <div style="display:flex;flex-direction:column;gap:0">
+      <div style="display:flex;align-items:center;gap:12px;padding:12px 16px;background:#0c101a;border:1px solid #1e293b;border-radius:10px;margin-bottom:4px">
+        <div style="width:32px;height:32px;border-radius:50%;background:linear-gradient(135deg,#8b5cf6,#7c3aed);display:flex;align-items:center;justify-content:center;font-size:0.85rem;flex-shrink:0">🎯</div>
+        <div>
+          <div style="font-weight:700;font-size:0.88rem;color:#f1f5f9">{role_1_name}</div>
+          <div style="font-size:0.78rem;color:#64748b;margin-top:2px">{role_1_action}</div>
+        </div>
+        <div style="margin-left:auto;padding:3px 10px;border-radius:20px;font-size:0.7rem;font-weight:600;background:rgba(139,92,246,0.15);color:#8b5cf6;border:1px solid rgba(139,92,246,0.3)">Step 1</div>
+      </div>
+      <div style="text-align:center;color:#334155;font-size:1.2rem;margin:2px 0">↓</div>
+      <div style="display:flex;align-items:center;gap:12px;padding:12px 16px;background:#0c101a;border:1px solid #1e293b;border-radius:10px;margin-bottom:4px">
+        <div style="width:32px;height:32px;border-radius:50%;background:linear-gradient(135deg,#00d4aa,#059669);display:flex;align-items:center;justify-content:center;font-size:0.85rem;flex-shrink:0">🧭</div>
+        <div>
+          <div style="font-weight:700;font-size:0.88rem;color:#f1f5f9">{role_2_name}</div>
+          <div style="font-size:0.78rem;color:#64748b;margin-top:2px">{role_2_action}</div>
+        </div>
+        <div style="margin-left:auto;padding:3px 10px;border-radius:20px;font-size:0.7rem;font-weight:600;background:rgba(0,212,170,0.15);color:#00d4aa;border:1px solid rgba(0,212,170,0.3)">Step 2</div>
+      </div>
+      <div style="text-align:center;color:#334155;font-size:1.2rem;margin:2px 0">↓</div>
+      <div style="display:flex;align-items:center;gap:12px;padding:12px 16px;background:#0c101a;border:1px solid #1e293b;border-radius:10px;margin-bottom:4px">
+        <div style="width:32px;height:32px;border-radius:50%;background:linear-gradient(135deg,#3b82f6,#1d4ed8);display:flex;align-items:center;justify-content:center;font-size:0.85rem;flex-shrink:0">💻</div>
+        <div>
+          <div style="font-weight:700;font-size:0.88rem;color:#f1f5f9">{role_3_name}</div>
+          <div style="font-size:0.78rem;color:#64748b;margin-top:2px">{role_3_action}</div>
+        </div>
+        <div style="margin-left:auto;padding:3px 10px;border-radius:20px;font-size:0.7rem;font-weight:600;background:rgba(59,130,246,0.15);color:#3b82f6;border:1px solid rgba(59,130,246,0.3)">Step 3</div>
+      </div>
+    </div>
+  </div>
+
+  <!-- COMMON MISTAKE -->
+  <div style="background:linear-gradient(135deg,rgba(239,68,68,0.08),rgba(239,68,68,0.03));border:1px solid rgba(239,68,68,0.25);border-radius:12px;padding:18px 24px;margin-bottom:16px">
+    <div style="font-size:0.7rem;color:#ef4444;font-weight:700;letter-spacing:2px;text-transform:uppercase;margin-bottom:8px">🚩 Common Mistake</div>
+    <div style="color:#fca5a5;font-size:0.88rem;line-height:1.6">{common_mistake}</div>
+  </div>
+
+  <!-- QUOTE -->
+  <div style="background:linear-gradient(135deg,rgba(0,212,170,0.08),rgba(139,92,246,0.08));border:1px solid rgba(0,212,170,0.2);border-radius:12px;padding:16px 24px;text-align:center">
+    <div style="color:#00d4aa;font-style:italic;font-size:0.9rem;font-weight:600">"{quote}"</div>
+    <div style="color:#475569;font-size:0.75rem;margin-top:6px">— AgileAdvisor 🤙</div>
+  </div>
+
+</div>
+
+TONE RULES:
+- Be like a coach who has seen it all and has zero patience for excuses
+- Use phrases like: "Let me be real", "Nobody asked but here's the truth", "If your team skips this..."
+- For bad practices, say: "Congratulations, you've invented chaos"
+- Always end with energy
+- NEVER ignore factual dataset matches
+- DATASET CARD should contain exact retrieved context before interpretation
+
+ROLE COLORS:
+- SM = #00d4aa
+- PO = #8b5cf6
+- Dev = #3b82f6
+- QA = #f59e0b
+- RTE = #ec4899
+"""
+
+# =========================
+# ROLE HIERARCHY DIAGRAM
+# =========================
+
+ROLE_HIERARCHY_HTML = """
+<div style="font-family:sans-serif;max-width:720px;margin:0 auto;padding:20px;">
+    <div style="text-align:center;margin-bottom:24px;">
+        <div style="font-size:1.3rem;font-weight:700;color:#f1f5f9;">Scrum Role Hierarchy & Outputs</div>
+        <div style="font-size:0.8rem;color:#64748b;margin-top:4px;">Who does what and what they produce</div>
+    </div>
+    
+    <div style="background:linear-gradient(135deg,#1e293b,#0f172a);border:1px solid #334155;border-radius:12px;padding:16px 20px;margin-bottom:12px;">
+        <div style="display:flex;align-items:center;gap:12px;">
+            <div style="width:36px;height:36px;border-radius:50%;background:linear-gradient(135deg,#64748b,#475569);display:flex;align-items:center;justify-content:center;font-size:1rem;">🏢</div>
+            <div>
+                <div style="font-weight:700;color:#f1f5f9;font-size:0.95rem;">Stakeholders / Business</div>
+                <div style="font-size:0.78rem;color:#94a3b8;">Vision, Budget, Market Needs</div>
+            </div>
+        </div>
+        <div style="margin-top:10px;padding-top:10px;border-top:1px solid #334155;">
+            <div style="font-size:0.7rem;color:#64748b;font-weight:600;letter-spacing:1px;text-transform:uppercase;margin-bottom:6px;">Outputs Assigned</div>
+            <div style="display:flex;flex-wrap:wrap;gap:6px;">
+                <span style="background:rgba(100,116,139,0.15);color:#94a3b8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(100,116,139,0.3);">Business Requirements</span>
+                <span style="background:rgba(100,116,139,0.15);color:#94a3b8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(100,116,139,0.3);">Product Vision</span>
+                <span style="background:rgba(100,116,139,0.15);color:#94a3b8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(100,116,139,0.3);">Funding</span>
+            </div>
+        </div>
+    </div>
+    
+    <div style="text-align:center;color:#334155;font-size:1.4rem;margin:4px 0;">↓</div>
+    
+    <div style="background:linear-gradient(135deg,#1e293b,#0f172a);border:1px solid rgba(139,92,246,0.3);border-left:4px solid #8b5cf6;border-radius:12px;padding:16px 20px;margin-bottom:12px;">
+        <div style="display:flex;align-items:center;gap:12px;">
+            <div style="width:36px;height:36px;border-radius:50%;background:linear-gradient(135deg,#8b5cf6,#7c3aed);display:flex;align-items:center;justify-content:center;font-size:1rem;">🎯</div>
+            <div>
+                <div style="font-weight:700;color:#f1f5f9;font-size:0.95rem;">Product Owner (PO)</div>
+                <div style="font-size:0.78rem;color:#94a3b8;">Maximizing Product Value</div>
+            </div>
+        </div>
+        <div style="margin-top:10px;padding-top:10px;border-top:1px solid #334155;">
+            <div style="font-size:0.7rem;color:#8b5cf6;font-weight:600;letter-spacing:1px;text-transform:uppercase;margin-bottom:6px;">Outputs Assigned</div>
+            <div style="display:flex;flex-wrap:wrap;gap:6px;">
+                <span style="background:rgba(139,92,246,0.15);color:#c4b5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(139,92,246,0.3);">Product Backlog</span>
+                <span style="background:rgba(139,92,246,0.15);color:#c4b5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(139,92,246,0.3);">Prioritized Stories</span>
+                <span style="background:rgba(139,92,246,0.15);color:#c4b5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(139,92,246,0.3);">Sprint Goal</span>
+                <span style="background:rgba(139,92,246,0.15);color:#c4b5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(139,92,246,0.3);">Release Planning</span>
+            </div>
+        </div>
+    </div>
+    
+    <div style="text-align:center;color:#334155;font-size:1.4rem;margin:4px 0;">↓</div>
+    
+    <div style="background:linear-gradient(135deg,#1e293b,#0f172a);border:1px solid rgba(0,212,170,0.3);border-left:4px solid #00d4aa;border-radius:12px;padding:16px 20px;margin-bottom:12px;">
+        <div style="display:flex;align-items:center;gap:12px;">
+            <div style="width:36px;height:36px;border-radius:50%;background:linear-gradient(135deg,#00d4aa,#059669);display:flex;align-items:center;justify-content:center;font-size:1rem;">🛡️</div>
+            <div>
+                <div style="font-weight:700;color:#f1f5f9;font-size:0.95rem;">Scrum Master (SM)</div>
+                <div style="font-size:0.78rem;color:#94a3b8;">Protector of Process & Team</div>
+            </div>
+        </div>
+        <div style="margin-top:10px;padding-top:10px;border-top:1px solid #334155;">
+            <div style="font-size:0.7rem;color:#00d4aa;font-weight:600;letter-spacing:1px;text-transform:uppercase;margin-bottom:6px;">Outputs Assigned</div>
+            <div style="display:flex;flex-wrap:wrap;gap:6px;">
+                <span style="background:rgba(0,212,170,0.15);color:#6ee7b7;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(0,212,170,0.3);">Impediment Removal</span>
+                <span style="background:rgba(0,212,170,0.15);color:#6ee7b7;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(0,212,170,0.3);">Team Coaching</span>
+                <span style="background:rgba(0,212,170,0.15);color:#6ee7b7;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(0,212,170,0.3);">Process Improvement</span>
+                <span style="background:rgba(0,212,170,0.15);color:#6ee7b7;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(0,212,170,0.3);">Shield from Distractions</span>
+            </div>
+        </div>
+    </div>
+    
+    <div style="text-align:center;color:#334155;font-size:1.4rem;margin:4px 0;">↓</div>
+    
+    <div style="background:linear-gradient(135deg,#1e293b,#0f172a);border:1px solid rgba(59,130,246,0.3);border-left:4px solid #3b82f6;border-radius:12px;padding:16px 20px;margin-bottom:12px;">
+        <div style="display:flex;align-items:center;gap:12px;">
+            <div style="width:36px;height:36px;border-radius:50%;background:linear-gradient(135deg,#3b82f6,#1d4ed8);display:flex;align-items:center;justify-content:center;font-size:1rem;">💻</div>
+            <div>
+                <div style="font-weight:700;color:#f1f5f9;font-size:0.95rem;">Development Team</div>
+                <div style="font-size:0.78rem;color:#94a3b8;">Cross-functional & Self-organizing</div>
+            </div>
+        </div>
+        <div style="margin-top:10px;padding-top:10px;border-top:1px solid #334155;">
+            <div style="font-size:0.7rem;color:#3b82f6;font-weight:600;letter-spacing:1px;text-transform:uppercase;margin-bottom:6px;">Outputs Assigned</div>
+            <div style="display:flex;flex-wrap:wrap;gap:6px;">
+                <span style="background:rgba(59,130,246,0.15);color:#93c5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(59,130,246,0.3);">Potentially Shippable Increment</span>
+                <span style="background:rgba(59,130,246,0.15);color:#93c5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(59,130,246,0.3);">Sprint Backlog Updates</span>
+                <span style="background:rgba(59,130,246,0.15);color:#93c5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(59,130,246,0.3);">Done Work (Definition of Done)</span>
+                <span style="background:rgba(59,130,246,0.15);color:#93c5fd;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(59,130,246,0.3);">Technical Excellence</span>
+            </div>
+        </div>
+    </div>
+    
+    <div style="text-align:center;color:#334155;font-size:1.4rem;margin:4px 0;">↓</div>
+    
+    <div style="background:linear-gradient(135deg,#1e293b,#0f172a);border:1px solid rgba(236,72,153,0.3);border-left:4px solid #ec4899;border-radius:12px;padding:16px 20px;">
+        <div style="display:flex;align-items:center;gap:12px;">
+            <div style="width:36px;height:36px;border-radius:50%;background:linear-gradient(135deg,#ec4899,#db2777);display:flex;align-items:center;justify-content:center;font-size:1rem;">🚂</div>
+            <div>
+                <div style="font-weight:700;color:#f1f5f9;font-size:0.95rem;">Release Train Engineer (RTE)</div>
+                <div style="font-size:0.78rem;color:#94a3b8;">SAFe — Program Level Facilitator</div>
+            </div>
+        </div>
+        <div style="margin-top:10px;padding-top:10px;border-top:1px solid #334155;">
+            <div style="font-size:0.7rem;color:#ec4899;font-weight:600;letter-spacing:1px;text-transform:uppercase;margin-bottom:6px;">Outputs Assigned</div>
+            <div style="display:flex;flex-wrap:wrap;gap:6px;">
+                <span style="background:rgba(236,72,153,0.15);color:#fbcfe8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(236,72,153,0.3);">Program Backlog</span>
+                <span style="background:rgba(236,72,153,0.15);color:#fbcfe8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(236,72,153,0.3);">PI Planning Facilitation</span>
+                <span style="background:rgba(236,72,153,0.15);color:#fbcfe8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(236,72,153,0.3);">Cross-team Sync</span>
+                <span style="background:rgba(236,72,153,0.15);color:#fbcfe8;padding:3px 10px;border-radius:6px;font-size:0.75rem;border:1px solid rgba(236,72,153,0.3);">Program Impediment Escalation</span>
+            </div>
+        </div>
+    </div>
+</div>
+"""
+
+# =========================
+# AI ADVISOR CLASS
+# =========================
+
+
+class AgileAdvisor:
+    """Handles AI generation with RAG context"""
+
+    def __init__(self, kb: KnowledgeBase):
+        self.kb = kb
+        self.config = CONFIG
+
+    def ask(self, question: str) -> Tuple[str, str, str, str]:
+        """
+        Main entry: retrieve context + generate HTML response.
+        Returns: (html_answer, quick_feed_card_html, fact_text, fact_tags_csv)
+        """
+        if not question or not question.strip():
+            return (
+                self._error_card("Please enter a question! Even Agile coaches need a prompt."),
+                "",
+                "",
+                "",
+            )
+
+        if len(question) > self.config.MAX_QUERY_LENGTH:
+            return (
+                self._error_card(
+                    f"Question too long ({len(question)} chars). Max: {self.config.MAX_QUERY_LENGTH}"
+                ),
+                "",
+                "",
+                "",
+            )
+
+        if not self.kb.groq_client:
+            return (
+                self._error_card(
+                    "Groq API not configured. Add GROQ_API_KEY in HF Spaces Settings > Secrets."
+                ),
+                "",
+                "",
+                "",
+            )
+
+        try:
+            docs, context = self.kb.query(question)
+            context = context[:1200]
+
+            top_fact = docs[0] if docs else ""
+            fact_tags = self.kb.auto_tag(top_fact) if top_fact else []
+            fact_tags_str = ",".join(fact_tags)
+
+            response = self.kb.groq_client.chat.completions.create(
+                model=self.config.GROQ_MODEL,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {
+                        "role": "user",
+                        "content": f"""
+RETRIEVED CONTEXT FROM KNOWLEDGE BASE:
+{context}
+
+USER QUESTION:
+{question}
+
+INSTRUCTIONS:
+1. Use the retrieved context to fill the DATASET CARD with exact facts
+2. Answer the question with wit and expertise
+3. Fill ALL placeholders: dataset_match, topic_title, explanation, key_point_1, key_point_2, key_point_3, role_1_name, role_1_action, role_2_name, role_2_action, role_3_name, role_3_action, common_mistake, quote
+4. Output valid HTML only
+""",
+                    },
+                ],
+                temperature=self.config.GROQ_TEMPERATURE,
+                max_tokens=self.config.GROQ_MAX_TOKENS,
+            )
+
+            content = response.choices[0].message.content
+            content = sanitize_html(content)
+            if not content.strip().startswith("<"):
+                content = f'<div style="font-family:sans-serif;max-width:800px;margin:0 auto;padding:20px">{content}</div>'
+
+            # Build quick-feed card for top fact
+            if top_fact:
+                tag_badges = "".join(
+                    [
+                        f'<span style="background:#1e293b;color:#00d4aa;padding:2px 8px;border-radius:4px;font-size:0.7rem;margin-right:4px;">{t}</span>'
+                        for t in fact_tags
+                    ]
+                )
+                fact_card_html = f"""
+                <div style="border:1px solid #334155;border-radius:10px;padding:14px;background:#0f172a;margin-top:12px;">
+                    <div style="font-size:0.75rem;color:#00d4aa;font-weight:700;margin-bottom:6px;">📦 Quick Feed — Top Retrieved Fact</div>
+                    <div style="color:#cbd5e1;font-size:0.88rem;line-height:1.5;margin-bottom:8px;">{top_fact}</div>
+                    <div style="display:flex;gap:6px;flex-wrap:wrap;">{tag_badges}</div>
+                </div>
+                """
+            else:
+                fact_card_html = ""
+                top_fact = ""
+                fact_tags_str = ""
+
+            return content, fact_card_html, top_fact, fact_tags_str
+
+        except Exception as e:
+            logger.error(f"AI generation failed: {e}")
+            return self._error_card(f"AI generation failed: {str(e)}"), "", "", ""
+
+    def analyze_transcript(self, transcript: str) -> str:
+        """ScrumLens: Audit a meeting transcript against the KB."""
+        if not transcript or not transcript.strip():
+            return self._error_card("Please paste a transcript first!")
+
+        if not self.kb.groq_client:
+            return self._error_card("Groq API not configured!")
+
+        try:
+            docs, context = self.kb.query(transcript[:400], n_results=3)
+            context = context[:1500]
+
+            prompt = f"""
+You are ScrumLens — a forensic Agile meeting auditor with zero patience for wasted time.
+Analyze the provided Scrum meeting transcript against the retrieved knowledge base facts.
+
+RETRIEVED KNOWLEDGE BASE CONTEXT:
+{context}
+
+TRANSCRIPT:
+{transcript}
+
+OUTPUT RULES:
+- Pure HTML only. No markdown. No plain text.
+- Start with a health score banner: 🟢 Healthy / 🟡 Needs Work / 🔴 Critical
+- List anti-patterns detected with references to KB facts
+- Provide per-role action items (PO, SM, Dev Team)
+- Include a "Quick Wins" section
+- Be witty, direct, and brutally honest
+
+Use this structure:
+<div style="font-family:sans-serif;max-width:800px;margin:0 auto;padding:8px">
+  <!-- Health Score -->
+  <div style="...">...</div>
+  <!-- Summary -->
+  <div style="...">...</div>
+  <!-- Red Flags -->
+  <div style="...">...</div>
+  <!-- Role Actions -->
+  <div style="...">...</div>
+  <!-- Quick Wins -->
+  <div style="...">...</div>
+</div>
+"""
+            response = self.kb.groq_client.chat.completions.create(
+                model=self.config.GROQ_MODEL,
+                messages=[
+                    {
+                        "role": "system",
+                        "content": "You are ScrumLens, an expert Agile auditor. Output pure HTML only.",
+                    },
+                    {"role": "user", "content": prompt},
+                ],
+                temperature=0.3,
+                max_tokens=1500,
+            )
+
+            content = response.choices[0].message.content
+            content = sanitize_html(content)
+            if not content.strip().startswith("<"):
+                content = f'<div style="font-family:sans-serif;max-width:800px;margin:0 auto;padding:20px">{content}</div>'
+            return content
+
+        except Exception as e:
+            logger.error(f"ScrumLens failed: {e}")
+            return self._error_card(f"ScrumLens analysis failed: {str(e)}")
+
+    def _error_card(self, message: str) -> str:
+        """Generate error HTML card"""
+        return (
+            '<div style="font-family:sans-serif;max-width:800px;margin:0 auto;padding:20px">'
+            '<div style="background:linear-gradient(135deg,#7f1d1d,#991b1b);'
+            "border:1px solid rgba(239,68,68,0.3);border-radius:12px;"
+            'padding:20px;color:#fca5a5">'
+            '<div style="font-size:1.2rem;font-weight:700;margin-bottom:8px">⚠️ Oops!</div>'
+            f'<div style="line-height:1.6">{message}</div>'
+            "</div></div>"
+        )
+
+
+# =========================
+# GRADIO UI BUILDER
+# =========================
+
+
+def build_app(kb: KnowledgeBase, advisor: AgileAdvisor):
+    """Build Gradio interface optimized for HF Spaces"""
+
+    custom_css = """
+    .stats-bar {
+        background: linear-gradient(135deg, #1e293b, #0f172a);
+        border-radius: 12px;
+        padding: 12px 16px;
+        margin-bottom: 16px;
+        border: 1px solid #334155;
+        color: #94a3b8;
+        font-size: 0.85rem;
+    }
+    .stats-bar strong {
+        color: #00d4aa;
+    }
+    .footer {
+        text-align: center;
+        margin-top: 24px;
+        color: #64748b;
+        font-size: 0.8rem;
+        padding: 16px;
+    }
+    """
+
+    with gr.Blocks(title="AgileAdvisor RAG v2", css=custom_css) as app:
+
+        # State for quick-feed
+        fact_text_st = gr.State("")
+        fact_tags_st = gr.State("")
+
+        # Header
+        gr.Markdown(
+            """
+        # 🧞 AgileAdvisor v2
+        ### Your RAG-powered Agile Coach with attitude — now with ScrumLens, Auto-Tags & Role Hierarchy
+        """
+        )
+
+        # Stats bar
+        stats = kb.get_stats()
+        status_color = "🟢" if stats.get("groq_ready") else "🔴"
+        gr.Markdown(
+            f"""
+        <div class="stats-bar">
+            {status_color} <strong>Knowledge Base:</strong> {stats.get('total_documents', 0)} documents | 
+            <strong>Storage:</strong> {stats.get('storage', 'N/A')} | 
+            <strong>Model:</strong> {CONFIG.GROQ_MODEL} |
+            <strong>Sync:</strong> 🔄 Auto-saves to Gist
+        </div>
+        """
+        )
+
+        # =====================
+        # TAB 1: ASK
+        # =====================
+        with gr.Tab("Ask AgileAdvisor ⚡"):
+            with gr.Row():
+                with gr.Column(scale=3):
+                    question_input = gr.Textbox(
+                        placeholder="e.g. What is Sprint Planning? Why do teams fail at Daily Standups?",
+                        label="Your Agile Question",
+                        lines=3,
+                        max_lines=5,
+                    )
+
+                    with gr.Row():
+                        ask_btn = gr.Button(
+                            "Ask the Wizard 🔮", variant="primary", size="lg", scale=3
+                        )
+                        clear_q_btn = gr.Button(
+                            "Clear 🗑️", variant="stop", size="sm", scale=1
+                        )
+
+                with gr.Column(scale=1):
+                    gr.Markdown(
+                        """
+                    **💡 Tips for best results:**
+                    - Ask about specific Scrum events
+                    - Mention roles (PO, SM, Dev Team)
+                    - Ask about anti-patterns
+                    - Keep questions focused
+                    """
+                    )
+
+            answer_output = gr.HTML(label="Response")
+
+            # Smart Quick-Feed Card
+            quick_feed_card = gr.HTML(label="Quick Feed Card")
+            with gr.Row():
+                quick_feed_btn = gr.Button(
+                    "➕ Feed This Fact to Dataset", size="sm", scale=2
+                )
+                quick_feed_status = gr.Textbox(
+                    label="Feed Status", interactive=False, scale=3
+                )
+
+            gr.Examples(
+                examples=[
+                    "What happens in Sprint Planning and who attends?",
+                    "Why is my Daily Standup taking 45 minutes?",
+                    "What does a Product Owner actually do all day?",
+                    "Explain the Definition of Done vs Definition of Ready",
+                    "Common mistakes during Sprint Retrospective",
+                    "What is velocity and how should we use it?",
+                    "My Scrum Master is just scheduling meetings, is that right?",
+                ],
+                inputs=question_input,
+                label="🔥 Quick Questions (Click to try)",
+            )
+
+            ask_btn.click(
+                fn=advisor.ask,
+                inputs=question_input,
+                outputs=[answer_output, quick_feed_card, fact_text_st, fact_tags_st],
+            )
+
+            quick_feed_btn.click(
+                fn=kb.feed_single_fact,
+                inputs=[fact_text_st, fact_tags_st],
+                outputs=quick_feed_status,
+            )
+
+            clear_q_btn.click(fn=lambda: "", inputs=None, outputs=question_input)
+
+        # =====================
+        # TAB 2: SCRUMLENS
+        # =====================
+        with gr.Tab("ScrumLens 🔍"):
+            gr.Markdown(
+                """
+                ## 🕵️ ScrumLens — Native RAG Transcript Auditor
+                Paste any Scrum meeting transcript below. ScrumLens will cross-check it against your knowledge base and surface anti-patterns, red flags, and role-specific action items.
+                """
+            )
+            transcript_input = gr.Textbox(
+                placeholder="Paste your Daily Standup, Sprint Planning, or Retrospective transcript here...",
+                label="Meeting Transcript",
+                lines=15,
+                max_lines=30,
+            )
+            with gr.Row():
+                analyze_btn = gr.Button(
+                    "Analyze Transcript", variant="primary", size="lg"
+                )
+                clear_transcript_btn = gr.Button("Clear 🗑️", variant="stop", size="sm")
+
+            lens_output = gr.HTML(label="ScrumLens Analysis")
+
+            analyze_btn.click(
+                fn=advisor.analyze_transcript,
+                inputs=transcript_input,
+                outputs=lens_output,
+            )
+            clear_transcript_btn.click(
+                fn=lambda: "", inputs=None, outputs=transcript_input
+            )
+
+        # =====================
+        # TAB 3: FEED DATASET
+        # =====================
+        with gr.Tab("Feed Dataset 📦"):
+            with gr.Row():
+                with gr.Column(scale=2):
+                    dataset_input = gr.Textbox(
+                        placeholder="""Paste new Agile knowledge here (one fact per line)...
+[ceremony] Sprint 0 is a preparation phase before the first official sprint
+[role] The Product Owner is the sole person responsible for managing the Product Backlog
+[anti-pattern] Skipping Sprint Retrospective leads to repeated mistakes and team burnout
+[gamification] Story points should never be used to compare individual developer performance""",
+                        label="New Agile Knowledge",
+                        lines=12,
+                        max_lines=25,
+                    )
+
+                    with gr.Row():
+                        preview_btn = gr.Button(
+                            "Preview Tags & Duplicates 👁️", variant="secondary", scale=2
+                        )
+                        feed_btn = gr.Button(
+                            "Feed Into Dataset 🚀", variant="primary", scale=2
+                        )
+                        clear_feed_btn = gr.Button("Clear 🗑️", variant="stop", scale=1)
+
+                with gr.Column(scale=1):
+                    gr.Markdown(
+                        """
+                    **📋 Feeding Guidelines:**
+
+                    ✅ **DO:**
+                    - One fact per line
+                    - Be specific and factual
+                    - Include role names (PO, SM, Dev)
+                    - Mention ceremony names clearly
+
+                    ❌ **DON'T:**
+                    - Add opinions or fluff
+                    - Duplicate existing facts
+                    - Add code or markdown
+                    - Exceed 10,000 characters
+
+                    **Auto-tags detected:** `ceremony`, `role`, `artifact`, `metric`, `anti-pattern`, `gamification`, `general`
+                    """
+                    )
+
+            feed_preview = gr.HTML(label="Tag & Duplicate Preview")
+            feed_output = gr.Textbox(label="Feed Status", interactive=False, lines=2)
+
+            preview_btn.click(
+                fn=kb.preview_feed, inputs=dataset_input, outputs=feed_preview
+            )
+            feed_btn.click(fn=kb.update_gist, inputs=dataset_input, outputs=feed_output)
+            clear_feed_btn.click(fn=lambda: "", inputs=None, outputs=dataset_input)
+
+        # =====================
+        # TAB 4: ROLE HIERARCHY
+        # =====================
+        with gr.Tab("Role Hierarchy 🏗️"):
+            gr.Markdown(
+                """
+                ## 🏗️ Scrum Role Hierarchy & Assigned Outputs
+                Visual reference for who produces what in the Scrum/SAFe ecosystem.
+                """
+            )
+            gr.HTML(ROLE_HIERARCHY_HTML)
+
+        # =====================
+        # TAB 5: ABOUT
+        # =====================
+        with gr.Tab("About ℹ️"):
+            gr.Markdown(
+                """
+            ## How AgileAdvisor Works
+
+            This is a **RAG (Retrieval-Augmented Generation)** application:
+
+            1. **Vector Database**: Stores Agile knowledge as embeddings using ChromaDB (with metadata tags)
+            2. **Retrieval**: When you ask a question, it finds the most relevant facts
+            3. **Generation**: Groq LLM combines retrieved facts with its knowledge to answer
+            4. **Dataset**: Lives in a GitHub Gist with embedded category tags and auto-syncs on every feed
+
+            ## New in v2
+
+            - **🔄 Persistent Gist Sync** — every feed auto-saves back to Gist
+            - **🔍 ScrumLens** — paste a transcript and audit it against your KB
+            - **🏷️ Auto-Tags** — facts are auto-labelled on feed (`[ceremony]`, `[role]`, etc.)
+            - **⚠️ Duplicate Detection** — live preview warns before saving
+            - **🏗️ Role Hierarchy** — visual diagram of roles & outputs
+            - **📦 Quick Feed** — one-click save from Ask panel
+
+            ## Architecture
+
+            ```
+            User Question ��� ChromaDB (Similarity Search + Tags) → Groq LLM + Context → HTML Response
+                                    ↑
+                            GitHub Gist (Tagged Source of Truth)
+            ```
+
+            ## Hero Tech Stack
+
+            - **Hero**: Sai Varakala ☀️ (@suryasticsai)
+            - **Frontend**: Gradio
+            - **Vector DB**: ChromaDB (persistent + metadata)
+            - **Embeddings**: all-MiniLM-L6-v2
+            - **LLM**: Groq (Llama 3.1 8B Instant)
+            - **Storage**: GitHub Gist (tagged) + Local Vector DB
+            """
+            )
+
+        # Footer
+        gr.Markdown(
+            """
+        <div class="footer">
+            🚀 Built with Love by Sai Surya ☀️ | 
+            💾 Data persists via GitHub Gist + Local Vector DB |
+            🔄 Auto-syncs on every feed |
+            🏷️ Auto-tagged knowledge base
+        </div>
+        """
+        )
+
+    return app
+
+
+# =========================
+# MAIN ENTRY
+# =========================
+
+
+def main():
+    """Initialize and launch on Hugging Face Spaces"""
+
+    has_groq = bool(os.environ.get("GROQ_API_KEY"))
+    has_github = bool(os.environ.get("GITHUB_TOKEN"))
+
+    logger.info(
+        f"Secrets check - GROQ_API_KEY: {'OK' if has_groq else 'MISSING'}, GITHUB_TOKEN: {'OK' if has_github else 'MISSING'}"
+    )
+
+    if not has_groq:
+        logger.warning(
+            "GROQ_API_KEY missing! AI responses will show error. Add it in HF Spaces Settings > Secrets."
+        )
+    if not has_github:
+        logger.warning(
+            "GITHUB_TOKEN missing! Dataset updates will show error. Add it in HF Spaces Settings > Secrets."
+        )
+
+    try:
+        logger.info("Initializing Knowledge Base...")
+        kb = KnowledgeBase()
+
+        advisor = AgileAdvisor(kb)
+
+        logger.info("Building Gradio UI...")
+        app = build_app(kb, advisor)
+
+        app.launch(
+            server_name="0.0.0.0",
+            server_port=7860,
+            share=False,
+            show_error=True,
+            quiet=False,
+            theme=gr.themes.Soft(),
+        )
+
+    except Exception as e:
+        logger.critical(f"Fatal error starting app: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    main()