initial deploy

.dockerignore

@@ -0,0 +1,4 @@
+__pycache__
+*.pyc
+.env
+*.db

.env.example

@@ -0,0 +1,5 @@
+GROQ_API_KEY=
+CEREBRAS_API_KEY=
+OPENROUTER_API_KEY=
+MISTRAL_API_KEY=
+SECRET_KEY=change-me

Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+EXPOSE 7860
+CMD ["gunicorn", "wsgi:app", "--bind", "0.0.0.0:7860", "--workers", "2", "--timeout", "120", "--access-logfile", "-"]

app/__init__.py

@@ -0,0 +1,42 @@
+"""DevKit — Flask app factory."""
+import os
+from flask import Flask
+from flask_wtf.csrf import CSRFProtect
+
+_csrf = CSRFProtect()
+
+
+def create_app():
+    app = Flask(__name__, template_folder="templates")
+    app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev-devkit-2026")
+    app.config["MAX_CONTENT_LENGTH"] = 30 * 1024 * 1024
+    _csrf.init_app(app)
+
+    from app.home.routes import bp as home_bp
+    app.register_blueprint(home_bp)
+
+    from app.tools.schema_detective.routes import bp as schema_detective_bp
+    app.register_blueprint(schema_detective_bp, url_prefix='/schema-detective')
+
+    from app.tools.test_forge.routes import bp as test_forge_bp
+    app.register_blueprint(test_forge_bp, url_prefix='/test-forge')
+
+    from app.tools.sql_whisperer.routes import bp as sql_whisperer_bp
+    app.register_blueprint(sql_whisperer_bp, url_prefix='/sql-whisperer')
+
+    from app.tools.doc_forge.routes import bp as doc_forge_bp
+    app.register_blueprint(doc_forge_bp, url_prefix='/doc-forge')
+
+    from app.tools.changelog_ai.routes import bp as changelog_ai_bp
+    app.register_blueprint(changelog_ai_bp, url_prefix='/changelog-ai')
+
+    from app.tools.git_narrator.routes import bp as git_narrator_bp
+    app.register_blueprint(git_narrator_bp, url_prefix='/git-narrator')
+
+    from flask import jsonify
+    @app.errorhandler(Exception)
+    def _handle_exc(e):
+        code = getattr(e, "code", 500)
+        return jsonify({"error": str(e)}), code
+
+    return app

app/core/ai.py

@@ -0,0 +1,219 @@
+"""Multi-provider AI engine. Runtime chain: Groq -> Cerebras -> OpenRouter -> Mistral -> Ollama."""
+import json, logging, os, re, requests
+
+logger = logging.getLogger(__name__)
+_OLLAMA_BASE = "http://localhost:11434"
+
+_PROVIDER_URLS = {
+    "groq":       "https://api.groq.com/openai/v1/chat/completions",
+    "cerebras":   "https://api.cerebras.ai/v1/chat/completions",
+    "openrouter": "https://openrouter.ai/api/v1/chat/completions",
+    "mistral":    "https://api.mistral.ai/v1/chat/completions",
+    "openai":     "https://api.openai.com/v1/chat/completions",
+}
+_FREE_MODELS = {
+    "groq":       "llama-3.1-8b-instant",
+    "cerebras":   "llama3.1-8b",
+    "openrouter": "google/gemma-3-12b-it:free",
+    "mistral":    "mistral-small-latest",
+}
+_PREMIUM_MODELS = {
+    "groq":       "llama-3.3-70b-versatile",
+    "cerebras":   "qwen-3-235b-a22b-instruct-2507",
+    "openrouter": "google/gemma-3-27b-it:free",
+    "mistral":    "mistral-medium-latest",
+    "openai":     "gpt-4o-mini",
+}
+_CHAIN_CFG = [
+    {"name": "groq",       "key_env": "GROQ_API_KEY",       "timeout": 30, "extra": {}},
+    {"name": "cerebras",   "key_env": "CEREBRAS_API_KEY",   "timeout": 30, "extra": {}},
+    {"name": "openrouter", "key_env": "OPENROUTER_API_KEY", "timeout": 45,
+     "extra": {"HTTP-Referer": "https://github.com/Moealsarraj", "X-Title": "AI Tools"}},
+    {"name": "mistral",    "key_env": "MISTRAL_API_KEY",    "timeout": 40, "extra": {}},
+]
+
+# Build the runtime provider list — all providers with valid keys
+_PROVIDERS = []
+for _p in _CHAIN_CFG:
+    _k = os.environ.get(_p["key_env"], "")
+    if _k:
+        _PROVIDERS.append({
+            "name":    _p["name"],
+            "url":     _PROVIDER_URLS[_p["name"]],
+            "model":   _FREE_MODELS[_p["name"]],
+            "key":     _k,
+            "timeout": _p["timeout"],
+            "extra":   _p["extra"],
+        })
+
+# Ollama fallback
+_OLLAMA_PROVIDER = None
+try:
+    _r = requests.get(f"{_OLLAMA_BASE}/api/tags", timeout=3)
+    if _r.status_code == 200:
+        _installed = [m["name"] for m in _r.json().get("models", [])]
+        if _installed:
+            _OLLAMA_PROVIDER = {"name": "ollama", "model": _installed[0]}
+except Exception:
+    pass
+
+_AI_AVAILABLE = bool(_PROVIDERS or _OLLAMA_PROVIDER)
+
+_RE_THINK = re.compile(r"<think>.*?</think>", re.DOTALL)
+_RE_OPEN  = re.compile(r"^```[a-z]*\n?", re.MULTILINE)
+_RE_CLOSE = re.compile(r"\n?```$", re.MULTILINE)
+
+def _clean(raw: str) -> str:
+    raw = _RE_THINK.sub("", raw).strip()
+    raw = _RE_OPEN.sub("", raw)
+    return _RE_CLOSE.sub("", raw).strip()
+
+def _post_openai(url, key, model, messages, max_tokens, extra_headers, timeout=60):
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    headers.update(extra_headers)
+    r = requests.post(url, headers=headers,
+        json={"model": model, "messages": messages, "max_tokens": max_tokens},
+        timeout=timeout)
+    r.raise_for_status()
+    return _clean(r.json()["choices"][0]["message"]["content"])
+
+def call_ai(messages: list, system: str = "", max_tokens: int = 2048,
+            api_key_row: dict | None = None) -> str:
+    if system:
+        messages = [{"role": "system", "content": system}] + messages
+    # Custom API key path (used by e.g. Wasit/Amin integrations)
+    if api_key_row:
+        provider = api_key_row.get("provider", "openai")
+        key      = api_key_row["key"]
+        url      = api_key_row.get("url") or _PROVIDER_URLS.get(provider, "")
+        model    = api_key_row.get("model") or _PREMIUM_MODELS.get(provider, "gpt-4o-mini")
+        if not url:
+            raise ValueError(f"No endpoint known for provider {provider!r}")
+        if provider == "claude":
+            r = requests.post("https://api.anthropic.com/v1/messages",
+                headers={"x-api-key": key, "anthropic-version": "2023-06-01",
+                         "content-type": "application/json"},
+                json={"model": "claude-sonnet-4-6", "max_tokens": max_tokens, "messages": messages},
+                timeout=60)
+            r.raise_for_status()
+            return _clean(r.json()["content"][0]["text"])
+        return _post_openai(url, key, model, messages, max_tokens, {})
+    if not _AI_AVAILABLE:
+        raise RuntimeError("No AI provider. Set GROQ_API_KEY or similar in .env")
+    # Ollama-only path
+    if not _PROVIDERS and _OLLAMA_PROVIDER:
+        r = requests.post(f"{_OLLAMA_BASE}/api/chat",
+            json={"model": _OLLAMA_PROVIDER["model"], "messages": messages, "stream": False},
+            timeout=120)
+        r.raise_for_status()
+        return _clean(r.json()["message"]["content"])
+    # Runtime chain: try each provider, fall back on 429 or transient errors
+    last_exc = None
+    for prov in _PROVIDERS:
+        try:
+            return _post_openai(
+                prov["url"], prov["key"], prov["model"],
+                messages, max_tokens, prov["extra"], prov["timeout"]
+            )
+        except requests.exceptions.HTTPError as e:
+            status = e.response.status_code if e.response is not None else 0
+            if status in (429, 503, 502):
+                logger.debug("Provider %s returned %s, trying next", prov["name"], status)
+                last_exc = e
+                continue
+            raise
+        except (requests.exceptions.ConnectionError,
+                requests.exceptions.Timeout) as e:
+            last_exc = e
+            continue
+    # Try Ollama as last resort
+    if _OLLAMA_PROVIDER:
+        r = requests.post(f"{_OLLAMA_BASE}/api/chat",
+            json={"model": _OLLAMA_PROVIDER["model"], "messages": messages, "stream": False},
+            timeout=120)
+        r.raise_for_status()
+        return _clean(r.json()["message"]["content"])
+    raise last_exc or RuntimeError("All AI providers failed or rate-limited")
+
+def _repair_json(text: str) -> str:
+    """Escape literal control characters inside JSON string values."""
+    result = []
+    in_str = False
+    esc = False
+    for c in text:
+        if esc:
+            result.append(c)
+            esc = False
+            continue
+        if c == '\\' and in_str:
+            result.append(c)
+            esc = True
+            continue
+        if c == '"':
+            in_str = not in_str
+            result.append(c)
+            continue
+        if in_str and c == '\n':
+            result.append('\\n')
+            continue
+        if in_str and c == '\r':
+            result.append('\\r')
+            continue
+        if in_str and c == '\t':
+            result.append('\\t')
+            continue
+        result.append(c)
+    return ''.join(result)
+
+def _extract_json(raw: str):
+    """Try progressively harder to extract valid JSON from raw text."""
+    raw = raw.strip()
+    # Direct parse
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+    # Repair literal newlines inside strings then retry
+    repaired = _repair_json(raw)
+    try:
+        return json.loads(repaired)
+    except json.JSONDecodeError:
+        pass
+    # Find first { or [ then walk to find matching closer
+    for source in (repaired, raw):
+        for start_ch, end_ch in [('{', '}'), ('[', ']')]:
+            idx = source.find(start_ch)
+            if idx == -1:
+                continue
+            depth = 0
+            in_str = False
+            esc = False
+            for i in range(idx, len(source)):
+                c = source[i]
+                if esc:
+                    esc = False
+                    continue
+                if c == '\\' and in_str:
+                    esc = True
+                    continue
+                if c == '"':
+                    in_str = not in_str
+                    continue
+                if in_str:
+                    continue
+                if c == start_ch:
+                    depth += 1
+                elif c == end_ch:
+                    depth -= 1
+                    if depth == 0:
+                        candidate = source[idx:i+1]
+                        try:
+                            return json.loads(candidate)
+                        except json.JSONDecodeError:
+                            break
+    raise ValueError(f"AI returned non-JSON: {raw[:200]}")
+
+def call_ai_json(messages: list, system: str = "", max_tokens: int = 2048,
+                 api_key_row: dict | None = None) -> dict | list:
+    raw = call_ai(messages, system=system, max_tokens=max_tokens, api_key_row=api_key_row)
+    return _extract_json(raw)

app/core/file_reader.py

@@ -0,0 +1,99 @@
+"""File text extractor — supports .docx, .pdf, .txt.
+
+Reusable: copy this file to any Flask project's app/core/ directory.
+Dependencies: pypdf>=4.0  (for PDF support — add to requirements.txt)
+DOCX and TXT use Python built-ins only (no extra packages needed).
+"""
+import io
+import zipfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+ALLOWED_EXTENSIONS = {".pdf", ".docx", ".txt"}
+MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB
+
+_WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def extract_text(file_storage) -> str:
+    """Extract plain text from a Werkzeug FileStorage object.
+
+    Supports .pdf, .docx, .txt files up to 10 MB.
+    Returns extracted text as a string.
+    Raises ValueError for unsupported types, oversized files, or parse errors.
+    """
+    filename = file_storage.filename or ""
+    ext = Path(filename).suffix.lower()
+
+    if ext not in ALLOWED_EXTENSIONS:
+        raise ValueError(
+            f"Unsupported file type '{ext or '(none)'}'. Allowed: PDF, DOCX, TXT"
+        )
+
+    data = file_storage.read()
+    if len(data) > MAX_FILE_SIZE:
+        raise ValueError("File too large (max 10 MB)")
+    if not data:
+        raise ValueError("File is empty")
+
+    if ext == ".txt":
+        return data.decode("utf-8", errors="replace").strip()
+    if ext == ".docx":
+        return _read_docx(io.BytesIO(data))
+    if ext == ".pdf":
+        return _read_pdf(io.BytesIO(data))
+
+    raise ValueError(f"Unhandled extension: {ext}")
+
+
+def _read_docx(stream: io.BytesIO) -> str:
+    """Extract text from a .docx file using built-in zipfile + xml.etree (no deps)."""
+    try:
+        with zipfile.ZipFile(stream) as z:
+            with z.open("word/document.xml") as f:
+                tree = ET.parse(f)
+    except (zipfile.BadZipFile, KeyError) as exc:
+        raise ValueError(f"Could not read Word document: {exc}")
+
+    root = tree.getroot()
+    paragraphs = []
+    for para in root.iter(f"{{{_WORD_NS}}}p"):
+        # Collect all text runs, preserving spaces
+        parts = []
+        for node in para.iter():
+            if node.tag == f"{{{_WORD_NS}}}t" and node.text:
+                parts.append(node.text)
+            elif node.tag == f"{{{_WORD_NS}}}br":
+                parts.append("\n")
+        text = "".join(parts).strip()
+        if text:
+            paragraphs.append(text)
+
+    text = "\n\n".join(paragraphs)
+    if not text.strip():
+        raise ValueError("No readable text found in the Word document")
+    return text
+
+
+def _read_pdf(stream: io.BytesIO) -> str:
+    """Extract text from a PDF using pypdf."""
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        raise ValueError("pypdf not installed — run: pip install pypdf")
+
+    try:
+        reader = PdfReader(stream)
+    except Exception as exc:
+        raise ValueError(f"Could not read PDF: {exc}")
+
+    pages = []
+    for page in reader.pages:
+        text = page.extract_text() or ""
+        if text.strip():
+            pages.append(text.strip())
+
+    text = "\n\n".join(pages)
+    if not text.strip():
+        raise ValueError("No readable text found in the PDF (may be image-based)")
+    return text

app/home/routes.py

@@ -0,0 +1,8 @@
+"""DevKit landing page."""
+from flask import Blueprint, render_template
+
+bp = Blueprint("home", __name__, template_folder="templates")
+
+@bp.route("/")
+def index():
+    return render_template("home/index.html")

app/home/templates/home/index.html

@@ -0,0 +1,152 @@
+{% extends "base.html" %}
+{% block title %}DevKit — Developer Toolkit{% endblock %}
+
+{% block content %}
+<div class="flex flex-col h-screen overflow-hidden">
+
+  <!-- Nav: same h-14 pattern as all tools -->
+  <nav class="flex items-center justify-between w-full px-6 py-2 bg-slate-50 h-14 z-50 border-b border-slate-200 shrink-0">
+    <div class="flex items-center gap-3">
+      <span class="w-8 h-8 rounded-lg bg-primary flex items-center justify-center">
+        <span class="material-symbols-outlined text-on-primary text-lg" style="font-variation-settings:'FILL' 1;">terminal</span>
+      </span>
+      <span class="text-lg font-semibold text-on-surface">DevKit</span>
+    </div>
+    <span class="text-xs font-semibold text-on-surface-variant bg-surface-container px-3 py-1.5 rounded-full">6 tools</span>
+  </nav>
+
+  <div class="flex flex-1 overflow-hidden">
+
+    <!-- Sidebar: same w-64 bg-slate-100 pattern as test-forge / agent-builder -->
+    <aside class="flex flex-col h-full w-64 p-4 gap-4 bg-slate-100 border-r border-slate-200 shrink-0 overflow-y-auto">
+      <div>
+        <p class="text-xs font-bold text-on-surface-variant uppercase tracking-widest mb-3">Categories</p>
+        <div class="space-y-1">
+          <div class="flex items-center gap-3 px-3 py-2 rounded-lg bg-white shadow-sm text-primary cursor-default">
+            <span class="material-symbols-outlined text-base">storage</span>
+            <span class="text-sm font-medium">Database</span>
+          </div>
+          <div class="flex items-center gap-3 px-3 py-2 rounded-lg text-on-surface-variant hover:bg-slate-200/60 transition-colors cursor-default">
+            <span class="material-symbols-outlined text-base">science</span>
+            <span class="text-sm font-medium">Code Quality</span>
+          </div>
+          <div class="flex items-center gap-3 px-3 py-2 rounded-lg text-on-surface-variant hover:bg-slate-200/60 transition-colors cursor-default">
+            <span class="material-symbols-outlined text-base">article</span>
+            <span class="text-sm font-medium">Documentation</span>
+          </div>
+          <div class="flex items-center gap-3 px-3 py-2 rounded-lg text-on-surface-variant hover:bg-slate-200/60 transition-colors cursor-default">
+            <span class="material-symbols-outlined text-base">history</span>
+            <span class="text-sm font-medium">Version History</span>
+          </div>
+        </div>
+      </div>
+    </aside>
+
+    <!-- Main workspace -->
+    <main class="flex-1 flex flex-col overflow-hidden bg-surface">
+
+      <!-- Action bar: matches the h-14 workspace bars inside tools -->
+      <div class="h-14 flex items-center justify-between px-6 bg-surface-container-low border-b border-slate-200 shrink-0">
+        <span class="text-xs font-bold text-on-surface-variant uppercase tracking-widest">Workspace</span>
+        <span class="text-xs text-outline">No signup required · Free</span>
+      </div>
+
+      <div class="flex-1 overflow-y-auto p-8">
+
+        <!-- Hero -->
+        <div class="mb-8">
+          <span class="text-[11px] font-semibold text-primary uppercase tracking-widest block mb-1">DevKit</span>
+          <h1 class="text-2xl font-bold text-on-surface tracking-tight">Developer Toolkit</h1>
+          <p class="text-sm text-on-surface-variant mt-2 max-w-xl leading-relaxed">Six tools for the day-to-day developer workflow — database auditing, SQL generation, test suites, documentation, and version history.</p>
+        </div>
+
+        <!-- Tool cards -->
+        <div class="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
+          <a href="/schema-detective/" class="group block bg-surface-container-lowest rounded-xl overflow-hidden border border-outline-variant/10 shadow-sm hover:shadow-md hover:-translate-y-0.5 transition-all">
+            <div class="h-11 flex items-center gap-3 px-4 bg-surface-container-low border-b border-slate-200/70 shrink-0">
+              <span class="w-6 h-6 rounded-md bg-primary flex items-center justify-center shrink-0">
+                <span class="material-symbols-outlined text-on-primary" style="font-size:14px;line-height:1;font-variation-settings:'FILL' 1;">table_view</span>
+              </span>
+              <span class="text-sm font-semibold text-on-surface">Schema Detective</span>
+              <span class="ml-auto flex items-center gap-0.5 text-xs font-medium text-outline group-hover:text-primary transition-colors">Open<span class="material-symbols-outlined text-sm leading-none ml-0.5">arrow_forward</span></span>
+            </div>
+            <div class="p-4">
+              <p class="text-sm text-on-surface-variant leading-relaxed">Audit database schemas for vulnerabilities, missing indexes, and design flaws.</p>
+            </div>
+          </a>
+          <a href="/test-forge/" class="group block bg-surface-container-lowest rounded-xl overflow-hidden border border-outline-variant/10 shadow-sm hover:shadow-md hover:-translate-y-0.5 transition-all">
+            <div class="h-11 flex items-center gap-3 px-4 bg-surface-container-low border-b border-slate-200/70 shrink-0">
+              <span class="w-6 h-6 rounded-md bg-primary flex items-center justify-center shrink-0">
+                <span class="material-symbols-outlined text-on-primary" style="font-size:14px;line-height:1;font-variation-settings:'FILL' 1;">science</span>
+              </span>
+              <span class="text-sm font-semibold text-on-surface">Test Forge</span>
+              <span class="ml-auto flex items-center gap-0.5 text-xs font-medium text-outline group-hover:text-primary transition-colors">Open<span class="material-symbols-outlined text-sm leading-none ml-0.5">arrow_forward</span></span>
+            </div>
+            <div class="p-4">
+              <p class="text-sm text-on-surface-variant leading-relaxed">Generate complete, runnable test suites across 8 frameworks from any source code.</p>
+            </div>
+          </a>
+          <a href="/sql-whisperer/" class="group block bg-surface-container-lowest rounded-xl overflow-hidden border border-outline-variant/10 shadow-sm hover:shadow-md hover:-translate-y-0.5 transition-all">
+            <div class="h-11 flex items-center gap-3 px-4 bg-surface-container-low border-b border-slate-200/70 shrink-0">
+              <span class="w-6 h-6 rounded-md bg-primary flex items-center justify-center shrink-0">
+                <span class="material-symbols-outlined text-on-primary" style="font-size:14px;line-height:1;font-variation-settings:'FILL' 1;">data_object</span>
+              </span>
+              <span class="text-sm font-semibold text-on-surface">SQL Whisperer</span>
+              <span class="ml-auto flex items-center gap-0.5 text-xs font-medium text-outline group-hover:text-primary transition-colors">Open<span class="material-symbols-outlined text-sm leading-none ml-0.5">arrow_forward</span></span>
+            </div>
+            <div class="p-4">
+              <p class="text-sm text-on-surface-variant leading-relaxed">Convert plain-English questions to SQL for PostgreSQL, MySQL, SQLite, and more.</p>
+            </div>
+          </a>
+          <a href="/doc-forge/" class="group block bg-surface-container-lowest rounded-xl overflow-hidden border border-outline-variant/10 shadow-sm hover:shadow-md hover:-translate-y-0.5 transition-all">
+            <div class="h-11 flex items-center gap-3 px-4 bg-surface-container-low border-b border-slate-200/70 shrink-0">
+              <span class="w-6 h-6 rounded-md bg-primary flex items-center justify-center shrink-0">
+                <span class="material-symbols-outlined text-on-primary" style="font-size:14px;line-height:1;font-variation-settings:'FILL' 1;">article</span>
+              </span>
+              <span class="text-sm font-semibold text-on-surface">Doc Forge</span>
+              <span class="ml-auto flex items-center gap-0.5 text-xs font-medium text-outline group-hover:text-primary transition-colors">Open<span class="material-symbols-outlined text-sm leading-none ml-0.5">arrow_forward</span></span>
+            </div>
+            <div class="p-4">
+              <p class="text-sm text-on-surface-variant leading-relaxed">Generate README, architecture overviews, and API docs from any GitHub repo.</p>
+            </div>
+          </a>
+          <a href="/changelog-ai/" class="group block bg-surface-container-lowest rounded-xl overflow-hidden border border-outline-variant/10 shadow-sm hover:shadow-md hover:-translate-y-0.5 transition-all">
+            <div class="h-11 flex items-center gap-3 px-4 bg-surface-container-low border-b border-slate-200/70 shrink-0">
+              <span class="w-6 h-6 rounded-md bg-primary flex items-center justify-center shrink-0">
+                <span class="material-symbols-outlined text-on-primary" style="font-size:14px;line-height:1;font-variation-settings:'FILL' 1;">update</span>
+              </span>
+              <span class="text-sm font-semibold text-on-surface">Changelog AI</span>
+              <span class="ml-auto flex items-center gap-0.5 text-xs font-medium text-outline group-hover:text-primary transition-colors">Open<span class="material-symbols-outlined text-sm leading-none ml-0.5">arrow_forward</span></span>
+            </div>
+            <div class="p-4">
+              <p class="text-sm text-on-surface-variant leading-relaxed">Turn commit history into changelogs for developers, users, or executives.</p>
+            </div>
+          </a>
+          <a href="/git-narrator/" class="group block bg-surface-container-lowest rounded-xl overflow-hidden border border-outline-variant/10 shadow-sm hover:shadow-md hover:-translate-y-0.5 transition-all">
+            <div class="h-11 flex items-center gap-3 px-4 bg-surface-container-low border-b border-slate-200/70 shrink-0">
+              <span class="w-6 h-6 rounded-md bg-primary flex items-center justify-center shrink-0">
+                <span class="material-symbols-outlined text-on-primary" style="font-size:14px;line-height:1;font-variation-settings:'FILL' 1;">history</span>
+              </span>
+              <span class="text-sm font-semibold text-on-surface">Git Narrator</span>
+              <span class="ml-auto flex items-center gap-0.5 text-xs font-medium text-outline group-hover:text-primary transition-colors">Open<span class="material-symbols-outlined text-sm leading-none ml-0.5">arrow_forward</span></span>
+            </div>
+            <div class="p-4">
+              <p class="text-sm text-on-surface-variant leading-relaxed">Transform raw git logs into readable project narratives and milestone timelines.</p>
+            </div>
+          </a>
+        </div>
+
+      </div>
+    </main>
+  </div>
+
+  <!-- Footer: same h-8 status bar as tools -->
+  <footer class="h-8 bg-surface-container-highest flex items-center justify-between px-6 text-[11px] font-medium text-on-surface-variant border-t border-slate-200 shrink-0">
+    <div class="flex items-center gap-4">
+      <div class="flex items-center gap-1.5"><div class="w-1.5 h-1.5 rounded-full bg-green-500"></div><span>DevKit</span></div>
+    </div>
+    <span>6 Tools · Free</span>
+  </footer>
+
+</div>
+{% endblock %}

app/templates/base.html

@@ -0,0 +1,121 @@
+<!DOCTYPE html>
+<html class="light" lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+<title>{% block title %}Competitive Intel{% endblock %}</title>
+<script src="https://cdn.tailwindcss.com?plugins=forms,container-queries"></script>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet"/>
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet"/>
+<script id="tailwind-config">
+tailwind.config = {
+  darkMode: "class",
+  theme: {
+    extend: {
+      colors: {
+        "error-container":            "#fe8983",
+        "on-primary-fixed-variant":   "#005bb0",
+        "on-secondary-fixed-variant": "#505d68",
+        "surface-bright":             "#f8f9fa",
+        "surface":                    "#f8f9fa",
+        "surface-tint":               "#005db5",
+        "primary":                    "#005db5",
+        "on-surface-variant":         "#586064",
+        "primary-fixed-dim":          "#bfd5ff",
+        "inverse-surface":            "#0c0f10",
+        "on-tertiary":                "#fbf7ff",
+        "background":                 "#f8f9fa",
+        "secondary":                  "#54616b",
+        "on-secondary-fixed":         "#34414b",
+        "on-background":              "#2b3437",
+        "surface-container":          "#eaeff1",
+        "tertiary-dim":               "#51516c",
+        "on-primary":                 "#f6f7ff",
+        "secondary-container":        "#d7e4f1",
+        "tertiary":                   "#5d5c78",
+        "primary-dim":                "#0052a0",
+        "on-error":                   "#fff7f6",
+        "surface-container-lowest":   "#ffffff",
+        "outline-variant":            "#abb3b7",
+        "on-secondary":               "#f5f9ff",
+        "inverse-primary":            "#5f9efb",
+        "tertiary-fixed-dim":         "#cbc9e9",
+        "outline":                    "#737c7f",
+        "on-secondary-container":     "#46535e",
+        "primary-container":          "#d6e3ff",
+        "error-dim":                  "#4e0309",
+        "error":                      "#9f403d",
+        "secondary-fixed":            "#d7e4f1",
+        "primary-fixed":              "#d6e3ff",
+        "inverse-on-surface":         "#9b9d9e",
+        "on-tertiary-container":      "#4a4a65",
+        "tertiary-fixed":             "#d9d7f8",
+        "on-tertiary-fixed-variant":  "#54546f",
+        "on-surface":                 "#2b3437",
+        "on-primary-fixed":           "#003f7d",
+        "on-primary-container":       "#00519e",
+        "on-tertiary-fixed":          "#383751",
+        "surface-container-low":      "#f1f4f6",
+        "surface-dim":                "#d1dce0",
+        "secondary-fixed-dim":        "#c9d6e3",
+        "on-error-container":         "#752121",
+        "surface-container-high":     "#e3e9ec",
+        "surface-variant":            "#dbe4e7",
+        "tertiary-container":         "#d9d7f8",
+        "surface-container-highest":  "#dbe4e7",
+        "secondary-dim":              "#48555f"
+      },
+      borderRadius: {
+        "DEFAULT": "0.25rem",
+        "lg":      "0.5rem",
+        "xl":      "0.75rem",
+        "full":    "9999px"
+      },
+      fontFamily: {
+        "headline": ["Inter", "sans-serif"],
+        "body":     ["Inter", "sans-serif"],
+        "label":    ["Inter", "sans-serif"]
+      }
+    }
+  }
+}
+</script>
+<style>
+  body { font-family: 'Inter', sans-serif; }
+  .material-symbols-outlined {
+    font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
+    vertical-align: middle;
+  }
+  .glass-effect { background: rgba(248,249,250,0.8); backdrop-filter: blur(12px); }
+  .ghost-border { outline: 1px solid rgba(171,179,183,0.15); }
+  ::-webkit-scrollbar { width: 6px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: #abb3b7; border-radius: 10px; }
+
+  /* Code editor (test-forge, schema-detective) */
+  .code-editor { font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace; }
+  .editor-bg   { background: #1e1e2e; color: #cdd6f4; }
+  /* Arabic text (arabic-bench) */
+  .arabic-text { font-family: 'Segoe UI', Tahoma, Arial, sans-serif; }
+  /* Scrollbar utilities */
+  .no-scrollbar::-webkit-scrollbar { display: none; }
+  .no-scrollbar { -ms-overflow-style: none; scrollbar-width: none; }
+  .custom-scrollbar::-webkit-scrollbar { width: 6px; }
+  .custom-scrollbar::-webkit-scrollbar-track { background: transparent; }
+  .custom-scrollbar::-webkit-scrollbar-thumb { background: #abb3b7; border-radius: 10px; }
+  /* Prompt-bench iOS overrides — scoped so they only affect prompt-bench internals */
+  .toolbar-blur { background: rgba(242,242,247,0.85); backdrop-filter: blur(20px); -webkit-backdrop-filter: blur(20px); }
+  .btn-primary  { display:inline-flex;align-items:center;gap:6px;padding:6px 14px;background:#007AFF;color:#fff;border-radius:8px;font-size:13px;font-weight:600;border:none;cursor:pointer; }
+  .btn-secondary{ display:inline-flex;align-items:center;gap:4px;padding:5px 10px;background:rgba(0,0,0,0.06);color:#3C3C43;border-radius:7px;font-size:12px;font-weight:500;border:none;cursor:pointer; }
+  .section-label{ font-size:11px;font-weight:600;color:#636366;text-transform:uppercase;letter-spacing:.06em; }
+  .sys-label    { color: #1C1C1E; }
+  .text-sys-label { color: #1C1C1E; }
+</style>
+{% block extra_head %}{% endblock %}
+<meta name="csrf-token" content="{{ csrf_token() }}"/>
+</head>
+<body class="bg-surface text-on-surface selection:bg-primary-container selection:text-on-primary-container">
+{% block content %}{% endblock %}
+{% block extra_scripts %}{% endblock %}
+</body>
+</html>

app/tools/changelog_ai/changelog.py

@@ -0,0 +1,94 @@
+"""Changelog.ai — transforms raw git commits into polished release notes."""
+from app.core.ai import call_ai_json
+
+_LANG_NAMES = {
+    "en": "English", "ar": "Arabic", "fr": "French", "es": "Spanish",
+    "de": "German",  "zh": "Chinese (Simplified)", "ja": "Japanese",
+    "pt": "Portuguese", "ru": "Russian", "tr": "Turkish",
+    "ko": "Korean",  "nl": "Dutch", "it": "Italian", "pl": "Polish",
+}
+
+_SYSTEM = """You are an expert technical writer who specializes in software release communications.
+You transform raw git commit history into clear, well-structured changelogs.
+You adapt your tone precisely to the target audience without over-explaining.
+Return ONLY valid JSON — no markdown fences, no preamble."""
+
+_AUDIENCE_NOTES = {
+    "Developer": (
+        "Write for software engineers. Use precise technical language. "
+        "Reference module names, APIs, and implementation details. "
+        "Include all commit types: feat, fix, perf, refactor. "
+        "Descriptions should be concise and technically accurate. "
+        "Skip chore/docs commits unless they have real developer impact."
+    ),
+    "User": (
+        "Write for end users with no technical background. "
+        "Translate technical changes into plain English benefits. "
+        "Focus on what users can NOW DO or what problems are SOLVED. "
+        "Only include feat and fix sections — no internal refactors, no chores. "
+        "Use active voice, 'You can now...', 'We fixed...' language."
+    ),
+    "Executive": (
+        "Write for C-suite and business stakeholders. "
+        "Focus exclusively on business impact, risk reduction, and strategic value. "
+        "Be brief: one punchy sentence per item maximum. "
+        "Skip low-level fixes unless they had business/availability impact. "
+        "Frame everything in terms of outcome, not implementation."
+    ),
+}
+
+_PROMPT_TMPL = """Transform the following git commits into a polished changelog.
+
+TARGET AUDIENCE: {audience}
+AUDIENCE INSTRUCTIONS: {audience_notes}
+
+GIT COMMITS / RAW CHANGES:
+---
+{commits}
+---
+
+Return a JSON object with EXACTLY these keys:
+{{
+  "sections": [
+    {{
+      "type": "<exactly one of: features | fixes | improvements | breaking>",
+      "items": [
+        {{
+          "title": "<short, clear title — max 8 words>",
+          "description": "<1-2 sentence description adapted to the target audience>"
+        }}
+      ]
+    }}
+  ]
+}}
+
+Rules:
+- sections: only include types that have actual items; omit empty sections
+- type ordering: breaking first, then features, then improvements, then fixes
+- breaking: only if a commit explicitly breaks backward compatibility
+- improvements: performance, refactors, dependency bumps with user impact
+- Filter chore/doc-only commits unless they carry meaningful impact for this audience
+- Each item title must be sentence-case and not end with a period
+- Minimum 1 item per section; group related commits into one item when appropriate"""
+
+
+def generate_changelog(commits: str, audience: str, language: str = "en") -> dict:
+    """Generate a polished changelog from raw git commits."""
+    audience_notes = _AUDIENCE_NOTES.get(audience, _AUDIENCE_NOTES["Developer"])
+    lang_name = _LANG_NAMES.get(language, "English")
+    lang_instruction = (
+        f"\n\nIMPORTANT: Write ALL text values in the JSON response in {lang_name}. "
+        "This includes all item titles and descriptions. "
+        "The JSON keys (type, sections, items, title, description) must remain in English."
+    ) if language != "en" else ""
+    prompt = _PROMPT_TMPL.format(
+        audience=audience,
+        audience_notes=audience_notes,
+        commits=commits[:6000],
+    ) + lang_instruction
+    result = call_ai_json(
+        [{"role": "user", "content": prompt}],
+        system=_SYSTEM,
+        max_tokens=2048,
+    )
+    return result or {}

app/tools/changelog_ai/routes.py

@@ -0,0 +1,32 @@
+"""Changelog.ai routes."""
+from flask import Blueprint, render_template, request, jsonify
+from .changelog import generate_changelog
+
+bp = Blueprint("changelog_ai", __name__, template_folder="templates")
+
+SUPPORTED_AUDIENCES = {"Developer", "User", "Executive"}
+
+
+@bp.route("/")
+def index():
+    return render_template("changelog_ai/index.html")
+
+
+@bp.route("/api/generate", methods=["POST"])
+def api_generate():
+    body = request.get_json(silent=True) or {}
+    commits   = (body.get("commits") or "").strip()
+    audience  = (body.get("audience") or "Developer").strip()
+    language  = (body.get("language") or "en").strip()
+
+    if not commits:
+        return jsonify({"error": "Paste some commits or change notes first"}), 400
+    if len(commits) < 20:
+        return jsonify({"error": "Too short — paste at least a few commit messages"}), 400
+    if audience not in SUPPORTED_AUDIENCES:
+        return jsonify({"error": f"Unsupported audience: {audience}"}), 400
+
+    result = generate_changelog(commits, audience, language=language)
+    if not result:
+        return jsonify({"error": "AI failed to generate changelog — please try again"}), 502
+    return jsonify(result)

app/tools/changelog_ai/templates/changelog_ai/index.html

@@ -0,0 +1,726 @@
+{% extends "base.html" %}
+{% block title %}Changelog.ai — AI Release Notes Generator{% endblock %}
+
+{% block content %}
+<!-- Top Nav -->
+<header class="flex justify-between items-center px-6 w-full sticky top-0 z-50 bg-white/80 backdrop-blur-md h-16 border-b border-slate-200/60">
+  <div class="flex items-center gap-6">
+    <span class="text-lg font-semibold text-on-surface tracking-tight">Changelog.ai</span>
+    <!-- Audience mode selector in nav -->
+    <div class="hidden md:flex gap-1 h-full items-end pb-0">
+      <button data-nav-audience="Developer"
+        class="nav-audience-btn px-4 pb-4 pt-4 text-sm font-medium text-on-surface-variant hover:text-on-surface transition-colors border-b-2 border-transparent">Developer</button>
+      <button data-nav-audience="User"
+        class="nav-audience-btn px-4 pb-4 pt-4 text-sm font-semibold text-blue-700 border-b-2 border-blue-700">User</button>
+      <button data-nav-audience="Executive"
+        class="nav-audience-btn px-4 pb-4 pt-4 text-sm font-medium text-on-surface-variant hover:text-on-surface transition-colors border-b-2 border-transparent">Executive</button>
+    </div>
+  </div>
+  <div class="flex items-center gap-3">
+    <button id="btn-download-pdf"
+      class="hidden bg-white border border-slate-200 hover:border-slate-300 text-on-surface px-4 py-2 rounded-lg text-sm font-medium transition-all shadow-sm flex items-center gap-2">
+      <span class="material-symbols-outlined text-sm" style="font-size:16px">picture_as_pdf</span>
+      Download PDF
+    </button>
+    <button id="btn-copy-md"
+      class="bg-primary hover:bg-primary-dim text-on-primary px-4 py-2 rounded-lg text-sm font-medium transition-all shadow-sm flex items-center gap-2">
+      <span id="copy-icon" class="material-symbols-outlined text-sm" style="font-size:16px">download</span>
+      <span id="copy-label">Copy Markdown</span>
+    </button>
+  </div>
+</header>
+
+<div class="flex h-[calc(100vh-4rem)] overflow-hidden">
+
+  <!-- Sidebar -->
+  <aside class="flex flex-col gap-2 p-4 h-full w-56 border-r border-slate-200/60 bg-slate-50 shrink-0">
+    <div class="flex items-center gap-3 px-2 mb-4">
+      <div class="w-8 h-8 rounded bg-primary flex items-center justify-center text-on-primary font-bold text-xs shadow-inner">CL</div>
+      <div>
+        <span class="text-sm font-semibold text-on-surface">Changelog.ai</span>
+        <span class="text-[10px] text-on-surface-variant uppercase tracking-wider font-bold block">Release Notes</span>
+      </div>
+    </div>
+    <nav class="flex-1 space-y-1">
+      <a class="flex items-center gap-3 px-3 py-2 bg-white text-blue-700 shadow-sm rounded-lg font-medium text-sm" href="#">
+        <span class="material-symbols-outlined" style="font-size:18px">history</span> Generator
+      </a>
+    </nav>
+  </aside>
+
+  <!-- Main Workspace -->
+  <main class="flex-1 flex overflow-hidden bg-surface">
+
+    <!-- Left Panel: Raw Input -->
+    <section class="w-2/5 p-5 border-r border-slate-200/60 flex flex-col gap-3 bg-white/50 shrink-0">
+      <div>
+        <span class="text-[10px] font-semibold text-on-surface-variant uppercase tracking-widest block mb-1">Source Input</span>
+        <h2 class="text-xl font-semibold text-on-surface">Raw Git History</h2>
+      </div>
+
+      <!-- Version + Date row -->
+      <div class="grid grid-cols-2 gap-3">
+        <div>
+          <label class="text-[10px] font-semibold text-on-surface-variant uppercase tracking-widest block mb-1">Version</label>
+          <input id="version-input" type="text" placeholder="v1.0.0"
+            class="w-full bg-white border border-slate-200 rounded-lg px-3 py-2 text-sm text-on-surface focus:ring-2 focus:ring-primary/20 outline-none">
+        </div>
+        <div>
+          <label class="text-[10px] font-semibold text-on-surface-variant uppercase tracking-widest block mb-1">Date</label>
+          <input id="date-input" type="date"
+            class="w-full bg-white border border-slate-200 rounded-lg px-3 py-2 text-sm text-on-surface focus:ring-2 focus:ring-primary/20 outline-none">
+        </div>
+      </div>
+
+      <!-- Language selector -->
+      <div>
+        <label class="text-[10px] font-semibold text-on-surface-variant uppercase tracking-widest block mb-1">Output Language</label>
+        <select id="lang-select"
+          class="w-full bg-white border border-slate-200 rounded-lg px-3 py-2 text-sm text-on-surface focus:ring-2 focus:ring-primary/20 outline-none">
+          <option value="en">English</option>
+          <option value="ar">Arabic</option>
+          <option value="fr">French</option>
+          <option value="es">Spanish</option>
+          <option value="de">German</option>
+          <option value="zh">Chinese (Simplified)</option>
+          <option value="ja">Japanese</option>
+          <option value="pt">Portuguese</option>
+          <option value="ru">Russian</option>
+          <option value="tr">Turkish</option>
+          <option value="ko">Korean</option>
+          <option value="nl">Dutch</option>
+          <option value="it">Italian</option>
+          <option value="pl">Polish</option>
+        </select>
+      </div>
+
+      <!-- Commits textarea -->
+      <div class="flex-1 relative">
+        <textarea id="commits-input"
+          class="w-full h-full bg-surface-container-lowest border-none ghost-border rounded-xl p-4 font-mono text-sm text-on-surface-variant focus:ring-2 focus:ring-primary/10 resize-none shadow-sm"
+          spellcheck="false"
+          placeholder="feat(api): add auth endpoints (f2a3b4)
+fix(worker): resolve memory leak in background worker (9a8b7c)
+perf(db): optimize query latency (d4e5f6)
+feat(ui): implement new dashboard layouts (1a2b3c)
+feat(auth): sso integration with Okta (5e6f7g)
+chore(deps): bump tailwindcss from 3.0 to 3.4
+docs: update readme with deployment steps
+refactor: clean up legacy charting utility"></textarea>
+      </div>
+
+      <div class="flex items-center gap-2">
+        <button id="btn-generate"
+          class="flex-1 bg-primary hover:bg-primary-dim text-on-primary py-3 rounded-xl font-semibold flex items-center justify-center gap-3 shadow-lg shadow-primary/20 transition-all active:scale-[0.98]">
+          <span class="material-symbols-outlined">auto_awesome</span>
+          Generate Polished Changelog
+        </button>
+        <button id="btn-try-demo"
+          class="shrink-0 bg-white border border-slate-200 hover:border-primary hover:text-primary text-on-surface-variant px-4 py-3 rounded-xl text-sm font-medium transition-all flex items-center gap-2 shadow-sm"
+          title="Load a sample to try the generator">
+          <span class="material-symbols-outlined" style="font-size:16px">play_circle</span>
+          Try a demo
+        </button>
+      </div>
+    </section>
+
+    <!-- Right Panel: Preview -->
+    <section class="flex-1 p-6 overflow-y-auto bg-surface-container-low flex flex-col gap-5">
+
+      <!-- Audience Toggle Pills -->
+      <div class="flex items-center justify-center shrink-0">
+        <div class="bg-surface-container-high p-1 rounded-xl flex gap-1">
+          <button data-pill-audience="Developer"
+            class="pill-btn px-4 py-2 text-sm font-medium rounded-lg text-on-surface-variant hover:text-on-surface transition-all">Developer</button>
+          <button data-pill-audience="User"
+            class="pill-btn px-6 py-2 text-sm font-semibold rounded-lg bg-white text-primary shadow-sm">User</button>
+          <button data-pill-audience="Executive"
+            class="pill-btn px-4 py-2 text-sm font-medium rounded-lg text-on-surface-variant hover:text-on-surface transition-all">Executive</button>
+        </div>
+      </div>
+
+      <!-- States -->
+      <div id="empty-state" class="flex-1 flex flex-col items-center justify-center text-center text-on-surface-variant">
+        <span class="material-symbols-outlined text-5xl text-outline mb-4">auto_awesome</span>
+        <p class="text-sm font-medium">Paste your commits and click Generate</p>
+        <p class="text-xs text-outline mt-1">Set version, audience, and language, then generate</p>
+      </div>
+
+      <div id="loading-state" class="hidden flex-1 flex flex-col items-center justify-center gap-4">
+        <div class="w-10 h-10 border-2 border-primary border-t-transparent rounded-full animate-spin"></div>
+        <p class="text-sm text-on-surface-variant">Generating changelog…</p>
+      </div>
+
+      <div id="error-state" class="hidden flex-1 flex flex-col items-center justify-center text-center">
+        <span class="material-symbols-outlined text-error text-4xl mb-3">error</span>
+        <p id="error-msg" class="text-sm text-error font-medium px-8"></p>
+      </div>
+
+      <!-- GitHub-style Preview Card -->
+      <div id="results-state" class="hidden max-w-3xl mx-auto w-full flex flex-col gap-4">
+        <div class="bg-white rounded-2xl shadow-sm border border-slate-200/50 p-8">
+          <!-- Release Header -->
+          <header class="mb-8 border-b border-slate-100 pb-6">
+            <div class="flex items-start justify-between mb-2">
+              <div>
+                <h1 id="release-title" class="text-3xl font-bold text-on-surface tracking-tight">Latest Release</h1>
+                <p id="release-meta" class="text-sm text-on-surface-variant mt-1"></p>
+              </div>
+              <span id="audience-badge" class="bg-secondary-container text-on-secondary-container text-xs font-bold px-3 py-1 rounded-full mt-1">User</span>
+            </div>
+          </header>
+          <!-- Sections rendered by JS -->
+          <div id="changelog-sections" class="space-y-8"></div>
+        </div>
+
+        <!-- Bento stats -->
+        <div class="grid grid-cols-3 gap-3">
+          <div class="col-span-2 bg-white/60 p-5 rounded-2xl ghost-border flex items-center gap-4">
+            <div class="p-3 bg-primary-container rounded-xl">
+              <span class="material-symbols-outlined text-primary" style="font-size:20px">checklist</span>
+            </div>
+            <div>
+              <p class="text-xs font-bold text-on-surface-variant uppercase tracking-wider">Changes</p>
+              <p id="stat-changes" class="text-lg font-bold text-on-surface">—</p>
+            </div>
+          </div>
+          <div class="bg-white/60 p-5 rounded-2xl ghost-border flex flex-col justify-center">
+            <p class="text-xs font-bold text-on-surface-variant uppercase tracking-wider mb-1">Audience</p>
+            <p id="stat-audience" class="text-xl font-bold text-on-surface">—</p>
+          </div>
+        </div>
+      </div>
+
+    </section>
+  </main>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script src="https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js"></script>
+<script>
+(function () {
+  const CSRF = document.querySelector('meta[name="csrf-token"]').content;
+
+  let selectedAudience = 'User';
+  let lastResult = null;
+
+  const commitsInput   = document.getElementById('commits-input');
+  const versionInput   = document.getElementById('version-input');
+  const dateInput      = document.getElementById('date-input');
+  const langSelect     = document.getElementById('lang-select');
+  const btnGenerate    = document.getElementById('btn-generate');
+  const btnCopyMd      = document.getElementById('btn-copy-md');
+  const btnDownloadPdf = document.getElementById('btn-download-pdf');
+  const copyIcon       = document.getElementById('copy-icon');
+  const copyLabel      = document.getElementById('copy-label');
+
+  const emptyState        = document.getElementById('empty-state');
+  const loadingState      = document.getElementById('loading-state');
+  const errorState        = document.getElementById('error-state');
+  const resultsState      = document.getElementById('results-state');
+  const errorMsg          = document.getElementById('error-msg');
+  const changelogSections = document.getElementById('changelog-sections');
+  const audienceBadge     = document.getElementById('audience-badge');
+  const releaseTitle      = document.getElementById('release-title');
+  const releaseMeta       = document.getElementById('release-meta');
+  const statChanges       = document.getElementById('stat-changes');
+  const statAudience      = document.getElementById('stat-audience');
+
+  // Set default date to today
+  dateInput.valueAsDate = new Date();
+
+  const SECTION_META = {
+    features:     { emoji: '\u2728', label: 'New Features',      bg: 'bg-blue-50',    dot: 'bg-blue-500',    pdfColor: [59, 130, 246]  },
+    fixes:        { emoji: '\uD83D\uDC1B', label: 'Bug Fixes',   bg: 'bg-red-50',     dot: 'bg-red-400',     pdfColor: [239, 68, 68]   },
+    improvements: { emoji: '\uD83D\uDE80', label: 'Improvements',bg: 'bg-emerald-50', dot: 'bg-emerald-500', pdfColor: [16, 185, 129]  },
+    breaking:     { emoji: '\u26A0\uFE0F', label: 'Breaking Changes', bg: 'bg-amber-50', dot: 'bg-amber-500', pdfColor: [245, 158, 11] },
+  };
+
+  const SECTION_LABELS = {
+    en: { features: 'New Features',       fixes: 'Bug Fixes',            improvements: 'Improvements',      breaking: 'Breaking Changes'     },
+    ar: { features: '\u0645\u064a\u0632\u0627\u062a \u062c\u062f\u064a\u062f\u0629', fixes: '\u0625\u0635\u0644\u0627\u062d \u0627\u0644\u0623\u062e\u0637\u0627\u0621', improvements: '\u062a\u062d\u0633\u064a\u0646\u0627\u062a', breaking: '\u062a\u063a\u064a\u064a\u0631\u0627\u062a \u062c\u0630\u0631\u064a\u0629' },
+    fr: { features: 'Nouvelles fonctionnalit\u00e9s', fixes: 'Correctifs',   improvements: 'Am\u00e9liorations',   breaking: 'Changements majeurs'  },
+    es: { features: 'Nuevas funciones',    fixes: 'Correcciones',         improvements: 'Mejoras',           breaking: 'Cambios importantes'  },
+    de: { features: 'Neue Funktionen',     fixes: 'Fehlerbehebungen',     improvements: 'Verbesserungen',    breaking: 'Grundlegende \u00c4nderungen' },
+    zh: { features: '\u65b0\u529f\u80fd',  fixes: '\u9519\u8bef\u4fee\u590d', improvements: '\u6539\u8fdb', breaking: '\u91cd\u5927\u53d8\u66f4' },
+    ja: { features: '\u65b0\u6a5f\u80fd',  fixes: '\u30d0\u30b0\u4fee\u6b63', improvements: '\u6539\u5584', breaking: '\u7834\u58ca\u7684\u5909\u66f4' },
+    pt: { features: 'Novos recursos',      fixes: 'Corre\u00e7\u00f5es',  improvements: 'Melhorias',         breaking: 'Mudan\u00e7as importantes' },
+    ru: { features: '\u041d\u043e\u0432\u044b\u0435 \u0444\u0443\u043d\u043a\u0446\u0438\u0438', fixes: '\u0418\u0441\u043f\u0440\u0430\u0432\u043b\u0435\u043d\u0438\u044f \u043e\u0448\u0438\u0431\u043e\u043a', improvements: '\u0423\u043b\u0443\u0447\u0448\u0435\u043d\u0438\u044f', breaking: '\u041a\u0440\u0438\u0442\u0438\u0447\u0435\u0441\u043a\u0438\u0435 \u0438\u0437\u043c\u0435\u043d\u0435\u043d\u0438\u044f' },
+    tr: { features: 'Yeni \u00f6zellikler', fixes: 'Hata d\u00fczeltmeleri', improvements: '\u0130yile\u015ftirmeler', breaking: 'B\u00fcy\u00fck de\u011fi\u015fiklikler' },
+    ko: { features: '\uc0c8\ub85c\uc6b4 \uae30\ub2a5', fixes: '\ubc84\uadf8 \uc218\uc815', improvements: '\uac1c\uc120 \uc0ac\ud56d', breaking: '\uc8fc\uc694 \ubcc0\uacbd \uc0ac\ud56d' },
+    nl: { features: 'Nieuwe functies',     fixes: 'Bugfixes',             improvements: 'Verbeteringen',     breaking: 'Grote wijzigingen'    },
+    it: { features: 'Nuove funzionalit\u00e0', fixes: 'Correzioni di bug', improvements: 'Miglioramenti',   breaking: 'Modifiche importanti' },
+    pl: { features: 'Nowe funkcje',        fixes: 'Poprawki b\u0142\u0119d\u00f3w', improvements: 'Ulepszenia', breaking: 'Prze\u0142omowe zmiany' },
+  };
+
+  function getSectionLabel(type) {
+    const lang   = langSelect.value;
+    const labels = SECTION_LABELS[lang] || SECTION_LABELS['en'];
+    return labels[type] || SECTION_META[type]?.label || type;
+  }
+
+  const RTL_LANGS = new Set(['ar']);
+  function isRtl() { return RTL_LANGS.has(langSelect.value); }
+
+  // html2pdf screenshots the DOM, so all languages/scripts render correctly.
+
+  // ── Audience sync ─────────────────────────────────────────────────────────
+  function setAudience(aud) {
+    selectedAudience = aud;
+    document.querySelectorAll('.nav-audience-btn').forEach(b => {
+      const on = b.dataset.navAudience === aud;
+      b.className = on
+        ? 'nav-audience-btn px-4 pb-4 pt-4 text-sm font-semibold text-blue-700 border-b-2 border-blue-700'
+        : 'nav-audience-btn px-4 pb-4 pt-4 text-sm font-medium text-on-surface-variant hover:text-on-surface transition-colors border-b-2 border-transparent';
+    });
+    document.querySelectorAll('.pill-btn').forEach(b => {
+      const on = b.dataset.pillAudience === aud;
+      b.className = on
+        ? 'pill-btn px-6 py-2 text-sm font-semibold rounded-lg bg-white text-primary shadow-sm'
+        : 'pill-btn px-4 py-2 text-sm font-medium rounded-lg text-on-surface-variant hover:text-on-surface transition-all';
+    });
+  }
+
+  document.querySelectorAll('.nav-audience-btn').forEach(b =>
+    b.addEventListener('click', () => setAudience(b.dataset.navAudience)));
+  document.querySelectorAll('.pill-btn').forEach(b =>
+    b.addEventListener('click', () => setAudience(b.dataset.pillAudience)));
+
+  setAudience('User');
+
+  // ── Generate ─────────────────────────────────────────────────────────────
+  btnGenerate.addEventListener('click', generate);
+
+  async function generate() {
+    const commits = commitsInput.value.trim();
+    if (!commits) { showError('Paste some commit messages first.'); return; }
+
+    showState('loading');
+    btnDownloadPdf.classList.add('hidden');
+
+    try {
+      const res = await fetch('/api/generate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-CSRFToken': CSRF },
+        body: JSON.stringify({
+          commits,
+          audience: selectedAudience,
+          language: langSelect.value,
+        })
+      });
+      const data = await res.json();
+      if (!res.ok) { showError(data.error || 'Generation failed — try again.'); return; }
+      lastResult = data;
+      renderChangelog(data);
+      showState('results');
+      btnDownloadPdf.classList.remove('hidden');
+    } catch (_) {
+      showError('Network error — is the server running?');
+    }
+  }
+
+  // ── Render changelog ──────────────────────────────────────────────────────
+  function renderChangelog(data) {
+    changelogSections.textContent = '';
+    const sections = data.sections || [];
+    let totalItems = 0;
+
+    // Apply RTL direction to the whole preview
+    resultsState.setAttribute('dir', isRtl() ? 'rtl' : 'ltr');
+
+    // Release header
+    const ver  = versionInput.value.trim();
+    const date = dateInput.value;
+    releaseTitle.textContent = ver ? ver : 'Latest Release';
+    const parts = [];
+    if (date) {
+      const d = new Date(date + 'T00:00:00');
+      parts.push(d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }));
+    }
+    releaseMeta.textContent = parts.join(' · ');
+
+    sections.forEach(section => {
+      const meta  = SECTION_META[section.type] || SECTION_META.improvements;
+      const items = section.items || [];
+      if (!items.length) return;
+      totalItems += items.length;
+
+      const sectionEl = document.createElement('section');
+
+      const headerRow = document.createElement('div');
+      headerRow.className = 'flex items-center gap-3 mb-4';
+
+      const emojiBox = document.createElement('span');
+      emojiBox.className = 'w-9 h-9 rounded-xl ' + meta.bg + ' flex items-center justify-center text-lg';
+      emojiBox.textContent = meta.emoji;
+
+      const title = document.createElement('h3');
+      title.className = 'text-base font-bold text-on-surface';
+      title.textContent = getSectionLabel(section.type);
+
+      const countBadge = document.createElement('span');
+      countBadge.className = 'ml-auto text-xs font-semibold text-on-surface-variant bg-slate-100 px-2 py-0.5 rounded-full';
+      countBadge.textContent = items.length + ' item' + (items.length !== 1 ? 's' : '');
+
+      headerRow.appendChild(emojiBox);
+      headerRow.appendChild(title);
+      headerRow.appendChild(countBadge);
+      sectionEl.appendChild(headerRow);
+
+      const box = document.createElement('div');
+      box.className = 'bg-slate-50/50 rounded-xl p-5 ghost-border';
+      const ul = document.createElement('ul');
+      ul.className = 'space-y-4';
+
+      items.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'flex items-start gap-3';
+
+        const dot = document.createElement('div');
+        dot.className = 'w-1.5 h-1.5 rounded-full mt-2 shrink-0 ' + meta.dot;
+
+        const textBlock = document.createElement('div');
+        const itemTitle = document.createElement('p');
+        itemTitle.className = 'font-semibold text-sm text-on-surface';
+        itemTitle.textContent = item.title || '';
+
+        const itemDesc = document.createElement('p');
+        itemDesc.className = 'text-xs text-on-surface-variant mt-0.5 leading-relaxed';
+        itemDesc.textContent = item.description || '';
+
+        textBlock.appendChild(itemTitle);
+        if (item.description) textBlock.appendChild(itemDesc);
+
+        li.appendChild(dot);
+        li.appendChild(textBlock);
+        ul.appendChild(li);
+      });
+
+      box.appendChild(ul);
+      sectionEl.appendChild(box);
+      changelogSections.appendChild(sectionEl);
+    });
+
+    audienceBadge.textContent = selectedAudience;
+    statChanges.textContent   = totalItems + ' item' + (totalItems !== 1 ? 's' : '');
+    statAudience.textContent  = selectedAudience;
+  }
+
+  // ── Copy Markdown ─────────────────────────────────────────────────────────
+  btnCopyMd.addEventListener('click', () => {
+    if (!lastResult) return;
+    const ver  = versionInput.value.trim();
+    const date = dateInput.value;
+    const lines = [];
+    if (ver)  lines.push('# ' + ver, '');
+    if (date) lines.push('_Released ' + date + '_', '');
+    lines.push('**Audience: ' + selectedAudience + '**', '');
+    (lastResult.sections || []).forEach(section => {
+      const meta = SECTION_META[section.type] || SECTION_META.improvements;
+      lines.push('## ' + meta.emoji + ' ' + getSectionLabel(section.type));
+      lines.push('');
+      (section.items || []).forEach(item => {
+        lines.push('- **' + (item.title || '') + '** — ' + (item.description || ''));
+      });
+      lines.push('');
+    });
+    navigator.clipboard.writeText(lines.join('\n')).then(() => {
+      copyIcon.textContent  = 'check';
+      copyLabel.textContent = 'Copied!';
+      setTimeout(() => {
+        copyIcon.textContent  = 'download';
+        copyLabel.textContent = 'Copy Markdown';
+      }, 2000);
+    });
+  });
+
+  // ── PDF Export ────────────────────────────────────────────────────────────
+  btnDownloadPdf.addEventListener('click', downloadPDF);
+
+  function downloadPDF() {
+    if (!lastResult) return;
+    btnDownloadPdf.disabled = true;
+    btnDownloadPdf.textContent = 'Generating…';
+    const el  = document.getElementById('results-state');
+    const ver = versionInput.value.trim();
+    const fname = (ver ? ver.replace(/\s+/g, '-') : 'changelog') + '-release-notes.pdf';
+    html2pdf().set({
+      margin: 10,
+      filename: fname,
+      image:       { type: 'jpeg', quality: 0.98 },
+      html2canvas: { scale: 2, useCORS: true, logging: false, backgroundColor: '#f8fafc' },
+      jsPDF:       { unit: 'mm', format: 'a4', orientation: 'portrait' },
+      pagebreak:   { mode: ['avoid-all', 'css'] },
+    }).from(el).save().then(() => {
+      btnDownloadPdf.disabled = false;
+      btnDownloadPdf.textContent = 'Download PDF';
+    });
+  }
+  /* legacy jsPDF body
+  function downloadPDF_legacy() {
+    const { jsPDF } = window.jspdf;
+    const doc = new jsPDF('p', 'mm', 'a4');
+    const PW = 210, PH = 297, M = 14;
+    const CW = PW - M * 2;
+
+    const NAVY  = [30, 41, 82];
+    const BLUE  = [59, 130, 246];
+    const SLATE = [100, 116, 139];
+    const LIGHT = [241, 245, 249];
+    const WHITE = [255, 255, 255];
+    const DARK  = [15, 23, 42];
+
+    const ver  = versionInput.value.trim();
+    const date = dateInput.value;
+    let totalPages = 1;
+    let y = 0;
+
+    function addPage() {
+      doc.addPage();
+      totalPages++;
+      y = 20;
+      drawPageFooter();
+    }
+
+    function checkY(needed) {
+      if (y + needed > PH - 20) addPage();
+    }
+
+    function drawPageFooter() {
+      doc.setFillColor(...LIGHT);
+      doc.rect(0, PH - 12, PW, 12, 'F');
+      doc.setFontSize(7);
+      doc.setTextColor(...SLATE);
+      doc.text('Generated by Changelog.ai', M, PH - 5);
+      doc.text('Page ' + doc.getCurrentPageInfo().pageNumber, PW - M, PH - 5, { align: 'right' });
+    }
+
+    // ── Header ──────────────────────────────────────────────────────────────
+    doc.setFillColor(...NAVY);
+    doc.rect(0, 0, PW, 30, 'F');
+    doc.setFillColor(...BLUE);
+    doc.rect(0, 30, PW, 2.5, 'F');
+
+    doc.setTextColor(...WHITE);
+    doc.setFontSize(18);
+    doc.setFont('helvetica', 'bold');
+    doc.text('RELEASE NOTES', M, 19);
+
+    if (ver) {
+      doc.setFontSize(12);
+      doc.setFont('helvetica', 'normal');
+      doc.text(ver, PW - M, 19, { align: 'right' });
+    }
+
+    y = 40;
+
+    // ── Meta row ────────────────────────────────────────────────────────────
+    doc.setFontSize(9);
+    doc.setFont('helvetica', 'normal');
+    doc.setTextColor(...SLATE);
+    if (date) {
+      const d = new Date(date + 'T00:00:00');
+      const dateStr = d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+      doc.text(dateStr, M, y);
+    }
+    doc.setFillColor(...BLUE);
+    doc.roundedRect(PW - M - 32, y - 4.5, 32, 6.5, 1.5, 1.5, 'F');
+    doc.setTextColor(...WHITE);
+    doc.setFontSize(7.5);
+    doc.setFont('helvetica', 'bold');
+    doc.text(selectedAudience.toUpperCase(), PW - M - 16, y - 0.2, { align: 'center' });
+
+    y += 10;
+
+    // ── Sections ─────────────────────────────────────────────────────────────
+    const rtl        = isRtl();
+    const textX      = rtl ? M + CW - 4 : M + 4;
+    const textAlign  = rtl ? 'right' : 'left';
+    const itemX      = rtl ? M + CW - 8 : M + 8;
+    const itemW      = CW - 14;
+    const dotX       = rtl ? M + CW - 3 : M + 3;
+    const countX     = rtl ? M + 4      : M + CW - 4;
+    const countAlign = rtl ? 'left'     : 'right';
+    const divX1      = rtl ? M          : M + 6;
+    const divX2      = rtl ? M + CW - 6 : M + CW;
+
+    const sections = lastResult.sections || [];
+    sections.forEach(section => {
+      const meta  = SECTION_META[section.type] || SECTION_META.improvements;
+      const items = section.items || [];
+      if (!items.length) return;
+
+      checkY(18);
+
+      // Section header band
+      const clr = meta.pdfColor || BLUE;
+      doc.setFillColor(clr[0] + Math.round((255 - clr[0]) * 0.88),
+                       clr[1] + Math.round((255 - clr[1]) * 0.88),
+                       clr[2] + Math.round((255 - clr[2]) * 0.88));
+      doc.roundedRect(M, y, CW, 9, 1.5, 1.5, 'F');
+
+      doc.setFontSize(9.5);
+      doc.setFont('helvetica', 'bold');
+      doc.setTextColor(...DARK);
+      doc.text(meta.emoji + '  ' + getSectionLabel(section.type), textX, y + 6.2, { align: textAlign });
+
+      const countStr = items.length + ' item' + (items.length !== 1 ? 's' : '');
+      doc.setFontSize(7.5);
+      doc.setFont('helvetica', 'normal');
+      doc.setTextColor(...SLATE);
+      doc.text(countStr, countX, y + 6.2, { align: countAlign });
+
+      y += 12;
+
+      items.forEach(item => {
+        const titleLines = doc.splitTextToSize(item.title || '', itemW);
+        const descLines  = item.description
+          ? doc.splitTextToSize(item.description, itemW)
+          : [];
+        const blockH = 4 + titleLines.length * 5 + (descLines.length > 0 ? 2 + descLines.length * 4.2 : 0) + 4;
+        checkY(blockH + 2);
+
+        // Dot
+        doc.setFillColor(...clr);
+        doc.circle(dotX, y + 2.8, 1, 'F');
+
+        // Title
+        doc.setFontSize(9);
+        doc.setFont('helvetica', 'bold');
+        doc.setTextColor(...DARK);
+        doc.text(titleLines, itemX, y + 4.5, { align: textAlign });
+        y += titleLines.length * 5;
+
+        // Description
+        if (descLines.length) {
+          doc.setFontSize(8);
+          doc.setFont('helvetica', 'normal');
+          doc.setTextColor(...SLATE);
+          doc.text(descLines, itemX, y + 3.5, { align: textAlign });
+          y += descLines.length * 4.2 + 2;
+        }
+
+        y += 4;
+
+        // Divider
+        doc.setDrawColor(226, 232, 240);
+        doc.setLineWidth(0.3);
+        doc.line(divX1, y, divX2, y);
+        y += 3;
+      });
+
+      y += 4;
+    });
+
+    // ── Stats footer area ────────────────────────────────────────────────────
+    checkY(24);
+    y += 2;
+    doc.setFillColor(...LIGHT);
+    doc.roundedRect(M, y, CW, 18, 2, 2, 'F');
+
+    let totalItems = 0;
+    sections.forEach(s => { totalItems += (s.items || []).length; });
+
+    doc.setFontSize(8);
+    doc.setFont('helvetica', 'bold');
+    doc.setTextColor(...SLATE);
+    doc.text('TOTAL CHANGES', M + 8, y + 7);
+    doc.setFontSize(13);
+    doc.setTextColor(...DARK);
+    doc.text(String(totalItems), M + 8, y + 14);
+
+    doc.setFontSize(8);
+    doc.setFont('helvetica', 'bold');
+    doc.setTextColor(...SLATE);
+    doc.text('AUDIENCE', PW / 2, y + 7, { align: 'center' });
+    doc.setFontSize(10);
+    doc.setTextColor(...DARK);
+    doc.setFont('helvetica', 'normal');
+    doc.text(selectedAudience, PW / 2, y + 14, { align: 'center' });
+
+    if (ver) {
+      doc.setFontSize(8);
+      doc.setFont('helvetica', 'bold');
+      doc.setTextColor(...SLATE);
+      doc.text('VERSION', M + CW - 8, y + 7, { align: 'right' });
+      doc.setFontSize(10);
+      doc.setFont('helvetica', 'normal');
+      doc.setTextColor(...DARK);
+      doc.text(ver, M + CW - 8, y + 14, { align: 'right' });
+    }
+
+    // Footer on first page
+    drawPageFooter();
+
+    const fname2 = (ver ? ver.replace(/\s+/g, '-') : 'changelog') + '-release-notes.pdf';
+    doc.save(fname2);
+  }*/
+
+  // ── State helpers ─────────────────────────────────────────────────────────
+  function showState(state) {
+    [emptyState, loadingState, errorState, resultsState].forEach(el => el.classList.add('hidden'));
+    const map = { empty: emptyState, loading: loadingState, error: errorState, results: resultsState };
+    if (map[state]) map[state].classList.remove('hidden');
+  }
+
+  function showError(msg) {
+    errorMsg.textContent = msg;
+    showState('error');
+  }
+
+  // ── Demo loader ───────────────────────────────────────────────────────────
+  const _DEMOS = [
+    {
+      version: 'v2.4.0',
+      commits: `- feat: add AI-powered auto-complete to search bar
+- feat: support bulk export to CSV and Excel
+- feat: dark mode toggle in user settings
+- fix: dashboard charts not loading on Safari
+- fix: email notifications sent twice on password reset
+- fix: file uploads failing for files over 50MB
+- perf: reduced page load time by 40% via lazy loading
+- security: patched XSS vulnerability in comment fields`,
+    },
+    {
+      version: 'v3.1.2',
+      commits: `- feat: offline mode — browse and save content without internet
+- feat: biometric login (Face ID / fingerprint)
+- feat: share to WhatsApp and Instagram Stories
+- fix: app crashing on Android 12 when opening camera
+- fix: notifications not appearing on iOS 17
+- fix: search results showing duplicates
+- improvement: 60% faster image loading
+- improvement: reduced battery drain by 25%`,
+    },
+    {
+      version: 'v1.8.0',
+      commits: `- feat: Claude 3 and GPT-4o model support
+- feat: streaming responses with real-time token display
+- feat: team workspaces with shared prompt libraries
+- feat: version history for all prompts
+- fix: API timeout errors on long responses
+- fix: syntax highlighting broken for Python 3.12
+- fix: keyboard shortcuts not working on Windows
+- breaking: removed deprecated v1 API endpoints
+- docs: updated quickstart guide and API reference`,
+    },
+  ];
+
+  let _demoIndex = 0;
+
+  function loadDemo() {
+    const demo = _DEMOS[_demoIndex % _DEMOS.length];
+    _demoIndex++;
+    commitsInput.value = demo.commits;
+    versionInput.value = demo.version;
+    // Trigger generate
+    generate();
+  }
+
+  window.loadDemo = loadDemo;
+
+  document.getElementById('btn-try-demo').addEventListener('click', loadDemo);
+})();
+</script>
+{% endblock %}

app/tools/doc_forge/db.py

@@ -0,0 +1,88 @@
+"""SQLite cache for generated docs."""
+import json
+import sqlite3
+import os
+
+_SCHEMA = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS repos (
+    id          INTEGER PRIMARY KEY,
+    owner       TEXT NOT NULL,
+    repo        TEXT NOT NULL,
+    info        TEXT NOT NULL,          -- JSON
+    tree        TEXT NOT NULL,          -- JSON array
+    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(owner, repo)
+);
+
+CREATE TABLE IF NOT EXISTS docs (
+    id          INTEGER PRIMARY KEY,
+    repo_id     INTEGER NOT NULL REFERENCES repos(id) ON DELETE CASCADE,
+    doc_type    TEXT NOT NULL,          -- readme | architecture | api
+    content     TEXT NOT NULL,          -- JSON
+    generated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(repo_id, doc_type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_docs_repo ON docs(repo_id);
+"""
+
+def get_db(path: str) -> sqlite3.Connection:
+    con = sqlite3.connect(path)
+    con.row_factory = sqlite3.Row
+    con.executescript(_SCHEMA)
+    con.commit()
+    return con
+
+
+def upsert_repo(db, owner: str, repo: str, info: dict, tree: list) -> int:
+    db.execute("""
+        INSERT INTO repos (owner, repo, info, tree)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(owner, repo) DO UPDATE SET
+            info=excluded.info, tree=excluded.tree, created_at=datetime('now')
+    """, (owner, repo, json.dumps(info), json.dumps(tree)))
+    db.commit()
+    row = db.execute("SELECT id FROM repos WHERE owner=? AND repo=?",
+                     (owner, repo)).fetchone()
+    return row["id"]
+
+
+def upsert_doc(db, repo_id: int, doc_type: str, content: dict):
+    db.execute("""
+        INSERT INTO docs (repo_id, doc_type, content)
+        VALUES (?, ?, ?)
+        ON CONFLICT(repo_id, doc_type) DO UPDATE SET
+            content=excluded.content, generated_at=datetime('now')
+    """, (repo_id, doc_type, json.dumps(content)))
+    db.commit()
+
+
+def get_docs(db, owner: str, repo: str) -> dict | None:
+    row = db.execute("SELECT id FROM repos WHERE owner=? AND repo=?",
+                     (owner, repo)).fetchone()
+    if not row:
+        return None
+    docs = db.execute("SELECT doc_type, content FROM docs WHERE repo_id=?",
+                      (row["id"],)).fetchall()
+    if not docs:
+        return None
+    result = {}
+    for d in docs:
+        result[d["doc_type"]] = json.loads(d["content"])
+    return result
+
+
+def list_recent(db, limit: int = 10) -> list:
+    rows = db.execute("""
+        SELECT r.owner, r.repo, r.info, r.created_at,
+               COUNT(d.id) as doc_count
+        FROM repos r LEFT JOIN docs d ON d.repo_id = r.id
+        GROUP BY r.id ORDER BY r.created_at DESC LIMIT ?
+    """, (limit,)).fetchall()
+    return [{"owner": r["owner"], "repo": r["repo"],
+             "info": json.loads(r["info"]),
+             "created_at": r["created_at"], "doc_count": r["doc_count"]}
+            for r in rows]

app/tools/doc_forge/doc_generator.py

@@ -0,0 +1,127 @@
+"""AI-powered documentation generator for DocForge."""
+import json
+from app.core.ai import call_ai, call_ai_json
+
+_README_SYSTEM = """You are a senior technical writer and developer advocate.
+Generate a comprehensive, beautiful GitHub README.md for the given repository.
+Output ONLY the raw Markdown content — no JSON, no preamble, no code fences.
+README must include: title with badges, description, features list, installation,
+usage with examples, configuration, contributing guide, and license section.
+Use real emoji sparingly. Make it genuinely useful, not generic."""
+
+_README_META_SYSTEM = """You are a technical analyst. Given a repository description, return ONLY valid JSON.
+Return a JSON object with EXACTLY these keys:
+{"summary": "2-3 sentence plain English summary", "tech_stack": ["tech1", "tech2"], "key_features": ["feature 1", "feature 2"], "complexity": "beginner|intermediate|advanced"}
+No markdown fences, no preamble."""
+
+_ARCH_SYSTEM = """You are a software architect. Analyze the repository and write a clear architecture document.
+Output ONLY raw Markdown — no JSON, no preamble, no code fences around the whole document.
+Structure your response with these sections:
+## Architecture Overview
+(2-3 paragraphs explaining the overall design)
+## Key Components
+(bullet list: component name — file path — what it does)
+## Data Flow
+(numbered steps describing how data moves through the system)
+## Mermaid Diagram
+(a ```mermaid code block with a graph LR or flowchart diagram)"""
+
+_ARCH_META_SYSTEM = """You are a technical analyst. Return ONLY valid JSON — no markdown, no preamble.
+{"components": [{"name": "X", "role": "Y", "file": "path/to/file"}], "mermaid": "graph LR\\n  A --> B"}"""
+
+_API_SYSTEM = """You are a technical writer. Extract and document all API endpoints,
+functions, and classes from the code files provided.
+Output ONLY raw Markdown — no JSON, no preamble.
+Structure with these sections:
+## API Endpoints
+(table: Method | Path | Description | Returns)
+## Functions
+(### FunctionName signature, then description and params as a bullet list)
+## Classes
+(### ClassName, then description and method list)"""
+
+
+def _build_context(repo_info: dict, tree: list[str], files: dict[str, str]) -> str:
+    ctx = f"Repository: {repo_info['full_name']}\n"
+    ctx += f"Description: {repo_info.get('description', 'No description')}\n"
+    ctx += f"Primary language: {repo_info.get('language', 'Unknown')}\n"
+    ctx += f"Stars: {repo_info.get('stars', 0)}  Forks: {repo_info.get('forks', 0)}\n"
+    if repo_info.get("topics"):
+        ctx += f"Topics: {', '.join(repo_info['topics'])}\n"
+    ctx += f"\nFile tree ({len(tree)} files, showing first 30):\n"
+    ctx += "\n".join(f"  {p}" for p in tree[:30])
+    ctx += "\n\nKey file contents:\n"
+    for path, content in list(files.items())[:5]:
+        ctx += f"\n--- {path} ---\n{content[:1500]}\n"
+    # Hard cap: Groq llama-3.1-8b has ~8k token context; keep prompt under ~12k chars
+    return ctx[:12000]
+
+
+def generate_readme(repo_info: dict, tree: list[str],
+                    files: dict[str, str], api_key_row=None) -> dict:
+    ctx = _build_context(repo_info, tree, files)
+    # Generate README as plain text (more reliable than embedding in JSON)
+    readme_text = call_ai(
+        [{"role": "user", "content": f"Generate a README.md for this repository:\n\n{ctx}"}],
+        system=_README_SYSTEM,
+        max_tokens=2048,
+        api_key_row=api_key_row,
+    )
+    # Generate metadata as simple JSON
+    try:
+        meta = call_ai_json(
+            [{"role": "user", "content": f"Analyze this repository and return metadata JSON:\n{ctx[:3000]}"}],
+            system=_README_META_SYSTEM,
+            max_tokens=512,
+            api_key_row=api_key_row,
+        )
+        if not isinstance(meta, dict):
+            meta = {}
+    except Exception:
+        meta = {}
+    return {
+        "readme": readme_text,
+        "summary": meta.get("summary", ""),
+        "tech_stack": meta.get("tech_stack", []),
+        "key_features": meta.get("key_features", []),
+        "complexity": meta.get("complexity", "intermediate"),
+    }
+
+
+def generate_architecture(repo_info: dict, tree: list[str],
+                           files: dict[str, str], api_key_row=None) -> dict:
+    ctx = _build_context(repo_info, tree, files)
+    overview_md = call_ai(
+        [{"role": "user", "content": f"Write an architecture document for this repository:\n\n{ctx}"}],
+        system=_ARCH_SYSTEM,
+        max_tokens=2048,
+        api_key_row=api_key_row,
+    )
+    try:
+        meta = call_ai_json(
+            [{"role": "user", "content": f"List the key components and a Mermaid diagram for this repo:\n{ctx[:3000]}"}],
+            system=_ARCH_META_SYSTEM,
+            max_tokens=1024,
+            api_key_row=api_key_row,
+        )
+        if not isinstance(meta, dict):
+            meta = {}
+    except Exception:
+        meta = {}
+    return {
+        "overview": overview_md,
+        "components": meta.get("components", []),
+        "mermaid": meta.get("mermaid", ""),
+    }
+
+
+def generate_api_docs(repo_info: dict, tree: list[str],
+                      files: dict[str, str], api_key_row=None) -> dict:
+    ctx = _build_context(repo_info, tree, files)
+    api_md = call_ai(
+        [{"role": "user", "content": f"Document the API, functions, and classes from this codebase:\n\n{ctx}"}],
+        system=_API_SYSTEM,
+        max_tokens=2048,
+        api_key_row=api_key_row,
+    )
+    return {"content": api_md}

app/tools/doc_forge/github_fetcher.py

@@ -0,0 +1,116 @@
+"""Fetches repository structure and key file contents from GitHub API."""
+import os
+import re
+import requests
+
+_GITHUB_API = "https://api.github.com"
+_SKIP_DIRS  = {".git", "node_modules", "__pycache__", ".venv", "venv",
+               "dist", "build", ".next", ".nuxt", "coverage", "htmlcov"}
+_CODE_EXTS  = {".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".rs", ".java",
+               ".rb", ".php", ".cs", ".cpp", ".c", ".h", ".swift", ".kt"}
+_DOC_EXTS   = {".md", ".rst", ".txt", ".yaml", ".yml", ".toml", ".json"}
+_PRIORITY   = ["README.md", "readme.md", "README.rst", "main.py", "app.py",
+               "index.js", "index.ts", "main.go", "src/main.rs", "setup.py",
+               "pyproject.toml", "package.json", "go.mod", "Cargo.toml"]
+
+
+def _headers():
+    token = os.environ.get("GITHUB_TOKEN", "")
+    h = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    return h
+
+
+def parse_repo_url(url: str) -> tuple[str, str]:
+    """Return (owner, repo) from a GitHub URL or owner/repo string."""
+    url = url.strip().rstrip("/")
+    # Match github.com/owner/repo — ignore /tree/, /blob/, /issues/ etc.
+    m = re.search(r"github\.com/([^/]+)/([^/?#\s]+)", url)
+    if m:
+        repo = m.group(2)
+        if repo.endswith(".git"):
+            repo = repo[:-4]
+        return m.group(1), repo
+    # Plain "owner/repo" shorthand
+    parts = url.split("/")
+    if len(parts) == 2 and parts[0] and parts[1]:
+        return parts[0], parts[1]
+    raise ValueError(f"Cannot parse GitHub URL: {url!r}")
+
+
+def get_repo_info(owner: str, repo: str) -> dict:
+    r = requests.get(f"{_GITHUB_API}/repos/{owner}/{repo}",
+                     headers=_headers(), timeout=15)
+    r.raise_for_status()
+    d = r.json()
+    return {
+        "full_name":    d.get("full_name", ""),
+        "description":  d.get("description", ""),
+        "language":     d.get("language", ""),
+        "stars":        d.get("stargazers_count", 0),
+        "forks":        d.get("forks_count", 0),
+        "topics":       d.get("topics", []),
+        "default_branch": d.get("default_branch", "main"),
+        "url":          d.get("html_url", ""),
+    }
+
+
+def get_file_tree(owner: str, repo: str, branch: str = "main",
+                  max_files: int = 150) -> list[str]:
+    """Return flat list of file paths, priority files first."""
+    r = requests.get(
+        f"{_GITHUB_API}/repos/{owner}/{repo}/git/trees/{branch}?recursive=1",
+        headers=_headers(), timeout=20)
+    if r.status_code == 404:
+        # Try main vs master
+        alt = "master" if branch == "main" else "main"
+        r = requests.get(
+            f"{_GITHUB_API}/repos/{owner}/{repo}/git/trees/{alt}?recursive=1",
+            headers=_headers(), timeout=20)
+    r.raise_for_status()
+    blobs = [item["path"] for item in r.json().get("tree", [])
+             if item["type"] == "blob"
+             and not any(seg in _SKIP_DIRS for seg in item["path"].split("/"))]
+
+    # Sort: priority first, then code, then docs, then rest
+    def rank(p):
+        name = p.split("/")[-1]
+        if p in _PRIORITY or name in _PRIORITY:
+            return 0
+        ext = os.path.splitext(p)[1].lower()
+        if ext in _CODE_EXTS:
+            return 1
+        if ext in _DOC_EXTS:
+            return 2
+        return 3
+
+    return sorted(blobs, key=rank)[:max_files]
+
+
+def fetch_file(owner: str, repo: str, path: str, branch: str = "main") -> str:
+    """Fetch raw content of a single file (max 50KB)."""
+    r = requests.get(
+        f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}",
+        headers=_headers(), timeout=15)
+    if r.status_code != 200:
+        return ""
+    text = r.text
+    return text[:50_000]  # cap at 50KB per file
+
+
+def fetch_key_files(owner: str, repo: str, tree: list[str],
+                    branch: str = "main", max_chars: int = 60_000) -> dict[str, str]:
+    """Fetch the most important files up to max_chars total."""
+    results: dict[str, str] = {}
+    total = 0
+    # Always try priority files first
+    ordered = [p for p in _PRIORITY if p in tree] + [p for p in tree if p not in _PRIORITY]
+    for path in ordered:
+        if total >= max_chars:
+            break
+        content = fetch_file(owner, repo, path, branch)
+        if content:
+            results[path] = content
+            total += len(content)
+    return results

app/tools/doc_forge/routes.py

@@ -0,0 +1,121 @@
+"""DocForge routes — generate full documentation for any GitHub repo."""
+import json
+import os
+from flask import (Blueprint, render_template, request, jsonify,
+                   current_app, Response)
+from .github_fetcher import (parse_repo_url, get_repo_info,
+                                      get_file_tree, fetch_key_files)
+from .doc_generator import (generate_readme, generate_architecture,
+                                     generate_api_docs)
+from .db import get_db, upsert_repo, upsert_doc, get_docs, list_recent
+
+bp = Blueprint("doc_forge", __name__, template_folder="templates")
+
+
+def _db():
+    db_path = os.path.join(os.path.dirname(current_app.root_path), "docforge.db")
+    return get_db(db_path)
+
+
+# ── Pages ──────────────────────────────────────────────────────────────────────
+
+@bp.route("/")
+def index():
+    db     = _db()
+    recent = list_recent(db)
+    return render_template("doc_forge/index.html", recent=recent)
+
+
+@bp.route("/docs/<owner>/<repo>")
+def docs_view(owner, repo):
+    db   = _db()
+    data = get_docs(db, owner, repo)
+    if not data:
+        return render_template("doc_forge/index.html", recent=list_recent(db),
+                               error=f"No docs found for {owner}/{repo}. Generate them first.")
+    return render_template("doc_forge/docs.html", owner=owner, repo=repo, data=data)
+
+
+# ── API ────────────────────────────────────────────────────────────────────────
+
+@bp.route("/api/analyze", methods=["POST"])
+def analyze():
+    """Step 1: fetch repo metadata + file tree. Returns info without generating docs."""
+    body = request.get_json(silent=True) or {}
+    url  = (body.get("url") or "").strip()
+    if not url:
+        return jsonify({"error": "repo_url is required"}), 400
+    try:
+        owner, repo = parse_repo_url(url)
+        info        = get_repo_info(owner, repo)
+        tree        = get_file_tree(owner, repo, info["default_branch"])
+        return jsonify({
+            "owner": owner, "repo": repo,
+            "info": info, "file_count": len(tree),
+            "tree_preview": tree[:20],
+        })
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 400
+
+
+@bp.route("/api/generate", methods=["POST"])
+def generate():
+    """Step 2: generate all docs for a repo."""
+    body  = request.get_json(silent=True) or {}
+    url   = (body.get("url") or "").strip()
+    types = body.get("types", ["readme", "architecture", "api"])
+    if not url:
+        return jsonify({"error": "url is required"}), 400
+    try:
+        owner, repo = parse_repo_url(url)
+        info        = get_repo_info(owner, repo)
+        tree        = get_file_tree(owner, repo, info["default_branch"])
+        files       = fetch_key_files(owner, repo, tree, info["default_branch"])
+        db          = _db()
+        repo_id     = upsert_repo(db, owner, repo, info, tree)
+        results     = {}
+
+        if "readme" in types:
+            readme = generate_readme(info, tree, files)
+            upsert_doc(db, repo_id, "readme", readme)
+            results["readme"] = readme
+
+        if "architecture" in types:
+            arch = generate_architecture(info, tree, files)
+            upsert_doc(db, repo_id, "architecture", arch)
+            results["architecture"] = arch
+
+        if "api" in types:
+            api_docs = generate_api_docs(info, tree, files)
+            upsert_doc(db, repo_id, "api", api_docs)
+            results["api"] = api_docs
+
+        return jsonify({"owner": owner, "repo": repo, "info": info, "docs": results})
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+
+@bp.route("/api/download/<owner>/<repo>/<doc_type>")
+def download(owner, repo, doc_type):
+    """Download a generated doc as a file."""
+    db   = _db()
+    data = get_docs(db, owner, repo)
+    if not data or doc_type not in data:
+        return jsonify({"error": "not found"}), 404
+    content = data[doc_type]
+    if doc_type == "readme":
+        text     = content.get("readme", "")
+        filename = "README.md"
+        mime     = "text/markdown"
+    else:
+        text     = json.dumps(content, indent=2, ensure_ascii=False)
+        filename = f"{doc_type}.json"
+        mime     = "application/json"
+    return Response(text, mimetype=mime,
+                    headers={"Content-Disposition": f'attachment; filename="{filename}"'})
+
+
+@bp.route("/api/recent")
+def recent():
+    db = _db()
+    return jsonify(list_recent(db))

app/tools/doc_forge/templates/doc_forge/docs.html

@@ -0,0 +1,417 @@
+{% extends "base.html" %}
+
+{% block title %}{{ owner }}/{{ repo }} — DocForge{% endblock %}
+
+{% block extra_head %}
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+<style>
+  body { padding-top: 0; }
+  .sidebar-link       { display: flex; align-items: center; gap: 0.75rem; color: #424753; padding: 0.75rem 1rem; font-size: 0.875rem; transition: all 0.15s; border-radius: 0.5rem; }
+  .sidebar-link:hover { color: #171c22; background: rgba(0,0,0,0.04); }
+  .sidebar-link.active{ color: #0051ae; border-left: 3px solid #0051ae; padding-left: calc(1rem - 3px); background: rgba(0,81,174,0.08); border-radius: 0.5rem; }
+  .tab-btn            { padding: 0.625rem 1.25rem; font-size: 0.875rem; font-weight: 600; color: #424753; border-bottom: 2px solid transparent; transition: all 0.15s; cursor: pointer; background: none; border-top: none; border-left: none; border-right: none; }
+  .tab-btn.active     { color: #0051ae; border-bottom-color: #0051ae; }
+  .tab-btn:hover:not(.active) { color: #171c22; }
+  .tab-panel          { display: none; }
+  .tab-panel.active   { display: block; }
+  .prose-doc h1, .prose-doc h2, .prose-doc h3 { font-weight: 700; color: #171c22; margin: 1.5rem 0 0.75rem; }
+  .prose-doc h1 { font-size: 1.75rem; }
+  .prose-doc h2 { font-size: 1.375rem; }
+  .prose-doc h3 { font-size: 1.125rem; }
+  .prose-doc p  { color: #424753; line-height: 1.75; margin-bottom: 1rem; }
+  .prose-doc ul { list-style: disc; padding-left: 1.5rem; margin-bottom: 1rem; color: #424753; }
+  .prose-doc ol { list-style: decimal; padding-left: 1.5rem; margin-bottom: 1rem; color: #424753; }
+  .prose-doc li { margin-bottom: 0.25rem; line-height: 1.75; }
+  .prose-doc code { background: #eaeef6; padding: 0.125rem 0.375rem; border-radius: 0.25rem; font-family: 'JetBrains Mono', monospace; font-size: 0.8125rem; color: #0051ae; }
+  .prose-doc pre  { background: #2c3137; color: #e2e8f0; padding: 1.25rem; border-radius: 0.5rem; overflow-x: auto; margin: 1rem 0; font-family: 'JetBrains Mono', monospace; font-size: 0.8125rem; line-height: 1.6; }
+  .prose-doc pre code { background: none; color: inherit; padding: 0; }
+  .prose-doc blockquote { border-left: 3px solid #0051ae; padding-left: 1rem; color: #424753; font-style: italic; margin: 1rem 0; }
+  .prose-doc a { color: #0051ae; text-decoration: underline; text-underline-offset: 2px; }
+  .prose-doc table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
+  .prose-doc th { background: #e4e8f0; padding: 0.75rem 1rem; text-align: left; font-size: 0.875rem; font-weight: 700; color: #171c22; }
+  .prose-doc td { padding: 0.75rem 1rem; font-size: 0.875rem; color: #424753; border-bottom: 1px solid #f0f4fc; }
+  .mermaid { background: #f7f9ff; padding: 1.5rem; border-radius: 0.5rem; text-align: center; }
+</style>
+{% endblock %}
+
+{% block content %}
+<div class="flex h-screen overflow-hidden pt-12">
+
+  {# ── Sidebar ───────────────────────────────────────────────────────────────── #}
+  <aside class="w-64 bg-surface-container-low border-r border-outline-variant/40 flex-shrink-0 flex flex-col overflow-y-auto">
+    <div class="px-5 py-5 border-b border-outline-variant/40">
+      <div class="flex items-center gap-3">
+        <div class="w-10 h-10 bg-primary rounded-lg flex items-center justify-center text-white font-bold text-lg">
+          {{ repo[0].upper() }}
+        </div>
+        <div class="min-w-0">
+          <h3 class="text-on-surface text-sm font-semibold leading-tight truncate">{{ repo }}</h3>
+          <p class="text-on-surface-variant text-xs font-mono truncate">{{ owner }}</p>
+        </div>
+      </div>
+    </div>
+
+    <nav class="flex-1 px-2 py-4 space-y-0.5">
+      <a href="/" class="sidebar-link">
+        <span class="material-symbols-outlined text-[20px]">home</span>
+        <span>Home</span>
+      </a>
+      {% if data.readme %}
+      <a href="#" onclick="switchTab('readme'); return false;" class="sidebar-link active" id="nav-readme">
+        <span class="material-symbols-outlined text-[20px]">description</span>
+        <span>README</span>
+      </a>
+      {% endif %}
+      {% if data.architecture %}
+      <a href="#" onclick="switchTab('architecture'); return false;" class="sidebar-link" id="nav-architecture">
+        <span class="material-symbols-outlined text-[20px]">account_tree</span>
+        <span>Architecture</span>
+      </a>
+      {% endif %}
+      {% if data.api %}
+      <a href="#" onclick="switchTab('api'); return false;" class="sidebar-link" id="nav-api">
+        <span class="material-symbols-outlined text-[20px]">api</span>
+        <span>API Docs</span>
+      </a>
+      {% endif %}
+    </nav>
+
+    <div class="p-4 border-t border-outline-variant/40 space-y-1">
+      <a href="https://github.com/{{ owner }}/{{ repo }}" target="_blank"
+         class="flex items-center gap-2 text-on-surface-variant hover:text-primary text-xs py-2 px-2 transition-colors rounded-lg">
+        <span class="material-symbols-outlined text-base">open_in_new</span>
+        View on GitHub
+      </a>
+      <a href="/" class="flex items-center gap-2 text-on-surface-variant hover:text-primary text-xs py-2 px-2 transition-colors rounded-lg">
+        <span class="material-symbols-outlined text-base">add</span>
+        New Repository
+      </a>
+    </div>
+  </aside>
+
+  {# ── Main Content ──────────────────────────────────────────────────────────── #}
+  <main class="flex-1 overflow-y-auto bg-background">
+    <div class="max-w-4xl mx-auto p-8">
+
+      {# Breadcrumb #}
+      <nav class="flex items-center gap-2 text-xs font-mono text-on-surface-variant mb-4">
+        <a href="/" class="hover:text-primary transition-colors">docforge</a>
+        <span class="material-symbols-outlined text-[12px]">chevron_right</span>
+        <span>{{ owner }}</span>
+        <span class="material-symbols-outlined text-[12px]">chevron_right</span>
+        <span class="text-primary font-bold">{{ repo }}</span>
+      </nav>
+
+      {# Page header #}
+      <header class="flex justify-between items-start mb-8 gap-4 flex-wrap">
+        <div>
+          <h1 class="text-3xl font-extrabold text-on-surface tracking-tight">{{ owner }}/{{ repo }}</h1>
+          {% if data.readme and data.readme.summary %}
+          <p class="text-on-surface-variant mt-2 max-w-2xl">{{ data.readme.summary }}</p>
+          {% endif %}
+          <div class="flex flex-wrap gap-2 mt-3">
+            {% if data.readme and data.readme.tech_stack %}
+              {% for tech in data.readme.tech_stack[:6] %}
+              <span class="px-2 py-0.5 rounded bg-secondary-container text-on-secondary-container text-[11px] font-mono">{{ tech }}</span>
+              {% endfor %}
+            {% endif %}
+            {% if data.readme and data.readme.complexity %}
+            <span class="px-2 py-0.5 rounded bg-tertiary-fixed text-on-tertiary-fixed text-[11px] font-mono">{{ data.readme.complexity }}</span>
+            {% endif %}
+          </div>
+        </div>
+        <div class="flex gap-2 flex-shrink-0">
+          <button onclick="copyCurrentTab()"
+                  class="bg-surface-container-high text-on-surface px-4 py-2 rounded-lg text-sm font-medium flex items-center gap-2 hover:bg-surface-container-highest transition-colors cursor-pointer">
+            <span id="copy-icon" class="material-symbols-outlined text-lg">content_copy</span>
+            Copy
+          </button>
+          <button onclick="downloadCurrentTab()"
+                  class="bg-gradient-to-r from-primary to-primary-container text-on-primary px-5 py-2 rounded-lg text-sm font-semibold flex items-center gap-2 shadow-lg shadow-primary/20 hover:-translate-y-0.5 transition-all cursor-pointer">
+            <span class="material-symbols-outlined text-lg">download</span>
+            Download
+          </button>
+        </div>
+      </header>
+
+      {# Tabs #}
+      <div class="flex gap-0 border-b border-outline-variant/30 mb-8">
+        {% if data.readme %}
+        <button class="tab-btn active" id="tab-readme" onclick="switchTab('readme')">README</button>
+        {% endif %}
+        {% if data.architecture %}
+        <button class="tab-btn" id="tab-architecture" onclick="switchTab('architecture')">Architecture</button>
+        {% endif %}
+        {% if data.api %}
+        <button class="tab-btn" id="tab-api" onclick="switchTab('api')">API Docs</button>
+        {% endif %}
+      </div>
+
+      {# ── README Panel ──────────────────────────────────────────────────────── #}
+      {% if data.readme %}
+      <div class="tab-panel active" id="panel-readme">
+        <div class="bg-surface-container-lowest rounded-xl p-8">
+          <div class="prose-doc" id="readme-content"></div>
+        </div>
+        {% if data.readme.key_features %}
+        <div class="mt-6 grid grid-cols-1 sm:grid-cols-2 gap-4">
+          {% for feat in data.readme.key_features[:4] %}
+          <div class="bg-surface-container-lowest p-5 rounded-xl flex items-start gap-3">
+            <span class="material-symbols-outlined text-primary text-xl mt-0.5 flex-shrink-0">check_circle</span>
+            <p class="text-sm text-on-surface-variant">{{ feat | e }}</p>
+          </div>
+          {% endfor %}
+        </div>
+        {% endif %}
+      </div>
+      {% endif %}
+
+      {# ── Architecture Panel ────────────────────────────────────────────────── #}
+      {% if data.architecture %}
+      <div class="tab-panel" id="panel-architecture">
+        {% if data.architecture.overview %}
+        <div class="bg-surface-container-lowest rounded-xl p-8 mb-6">
+          <h2 class="text-xl font-bold text-on-surface mb-4 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-primary rounded-full flex-shrink-0"></span>
+            Overview
+          </h2>
+          <div id="arch-overview" class="prose-doc"></div>
+          <script>document.getElementById('arch-overview').innerHTML = DOMPurify.sanitize(marked.parse({{ data.architecture.overview | tojson }}));</script>
+        </div>
+        {% endif %}
+
+        {% if data.architecture.mermaid %}
+        <div class="bg-surface-container-lowest rounded-xl p-8 mb-6">
+          <h2 class="text-xl font-bold text-on-surface mb-6 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-primary-container rounded-full flex-shrink-0"></span>
+            System Diagram
+          </h2>
+          <div class="mermaid">{{ data.architecture.mermaid | e }}</div>
+        </div>
+        {% endif %}
+
+        {% if data.architecture.components %}
+        <div class="bg-surface-container-lowest rounded-xl p-8 mb-6">
+          <h2 class="text-xl font-bold text-on-surface mb-6 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-tertiary rounded-full flex-shrink-0"></span>
+            Components
+          </h2>
+          <div class="space-y-4">
+            {% for comp in data.architecture.components %}
+            <div class="bg-surface-container-low p-5 rounded-xl">
+              <h3 class="font-bold text-on-surface text-sm mb-1 font-mono">
+                {{ (comp.name if comp is mapping else comp) | e }}
+              </h3>
+              {% if comp is mapping and comp.description %}
+              <p class="text-sm text-on-surface-variant">{{ comp.description | e }}</p>
+              {% endif %}
+              {% if comp is mapping and comp.responsibilities %}
+              <ul class="mt-2 space-y-1">
+                {% for r in comp.responsibilities %}
+                <li class="text-xs text-on-surface-variant flex items-start gap-2">
+                  <span class="material-symbols-outlined text-outline text-sm mt-0.5 flex-shrink-0">arrow_right</span>
+                  {{ r | e }}
+                </li>
+                {% endfor %}
+              </ul>
+              {% endif %}
+            </div>
+            {% endfor %}
+          </div>
+        </div>
+        {% endif %}
+
+        {% if data.architecture.data_flow %}
+        <div class="bg-surface-container-lowest rounded-xl p-8">
+          <h2 class="text-xl font-bold text-on-surface mb-4 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-secondary rounded-full flex-shrink-0"></span>
+            Data Flow
+          </h2>
+          <p class="text-on-surface-variant leading-relaxed">{{ data.architecture.data_flow | e }}</p>
+        </div>
+        {% endif %}
+      </div>
+      {% endif %}
+
+      {# ── API Panel ────────────────────────────────────────────────────────── #}
+      {% if data.api %}
+      <div class="tab-panel" id="panel-api">
+
+        {% if data.api.endpoints %}
+        <div class="bg-surface-container-lowest rounded-xl p-8 mb-6">
+          <h2 class="text-xl font-bold text-on-surface mb-6 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-primary rounded-full flex-shrink-0"></span>
+            Endpoints
+          </h2>
+          <div class="overflow-hidden rounded-xl bg-surface-container-low">
+            <table class="w-full text-left">
+              <thead class="bg-surface-container-high">
+                <tr>
+                  <th class="px-5 py-3 text-xs font-bold text-on-surface uppercase tracking-wide">Method</th>
+                  <th class="px-5 py-3 text-xs font-bold text-on-surface uppercase tracking-wide">Path</th>
+                  <th class="px-5 py-3 text-xs font-bold text-on-surface uppercase tracking-wide">Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                {% for ep in data.api.endpoints %}
+                {% set method = ep.method if ep is mapping else 'GET' %}
+                <tr class="hover:bg-surface-container-highest transition-colors">
+                  <td class="px-5 py-3">
+                    <span class="font-mono text-xs font-bold
+                      {% if method == 'GET' %}text-green-600
+                      {% elif method == 'POST' %}text-blue-600
+                      {% elif method in ('PUT','PATCH') %}text-purple-600
+                      {% elif method == 'DELETE' %}text-red-600
+                      {% else %}text-on-surface{% endif %}">
+                      {{ method | e }}
+                    </span>
+                  </td>
+                  <td class="px-5 py-3 font-mono text-xs text-on-surface">
+                    {{ (ep.path if ep is mapping else ep) | e }}
+                  </td>
+                  <td class="px-5 py-3 text-sm text-on-surface-variant">
+                    {{ (ep.description if ep is mapping else '') | e }}
+                  </td>
+                </tr>
+                {% endfor %}
+              </tbody>
+            </table>
+          </div>
+        </div>
+        {% endif %}
+
+        {% if data.api.functions %}
+        <div class="bg-surface-container-lowest rounded-xl p-8 mb-6">
+          <h2 class="text-xl font-bold text-on-surface mb-6 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-primary-container rounded-full flex-shrink-0"></span>
+            Functions
+          </h2>
+          <div class="space-y-4">
+            {% for fn in data.api.functions %}
+            <div class="bg-surface-container-low p-5 rounded-xl">
+              <p class="font-mono text-sm font-bold text-on-surface mb-1">
+                {{ (fn.name if fn is mapping else fn) | e }}{% if fn is mapping and fn.signature %}({{ fn.signature | e }}){% endif %}
+              </p>
+              {% if fn is mapping and fn.description %}
+              <p class="text-sm text-on-surface-variant">{{ fn.description | e }}</p>
+              {% endif %}
+              {% if fn is mapping and fn.returns %}
+              <p class="text-xs text-outline mt-2 font-mono">→ {{ fn.returns | e }}</p>
+              {% endif %}
+            </div>
+            {% endfor %}
+          </div>
+        </div>
+        {% endif %}
+
+        {% if data.api.classes %}
+        <div class="bg-surface-container-lowest rounded-xl p-8">
+          <h2 class="text-xl font-bold text-on-surface mb-6 flex items-center gap-3">
+            <span class="w-1.5 h-5 bg-tertiary rounded-full flex-shrink-0"></span>
+            Classes
+          </h2>
+          <div class="space-y-4">
+            {% for cls in data.api.classes %}
+            <div class="bg-surface-container-low p-5 rounded-xl">
+              <p class="font-mono text-sm font-bold text-on-surface mb-1">
+                class {{ (cls.name if cls is mapping else cls) | e }}
+              </p>
+              {% if cls is mapping and cls.description %}
+              <p class="text-sm text-on-surface-variant">{{ cls.description | e }}</p>
+              {% endif %}
+            </div>
+            {% endfor %}
+          </div>
+        </div>
+        {% endif %}
+
+        {% if not data.api.endpoints and not data.api.functions and not data.api.classes %}
+          {% if data.api.content %}
+          <div class="bg-surface-container-lowest rounded-xl p-8">
+            <div id="api-md-content" class="prose-doc"></div>
+          </div>
+          <script>
+            document.getElementById('api-md-content').innerHTML =
+              DOMPurify.sanitize(marked.parse({{ data.api.content | tojson }}));
+          </script>
+          {% else %}
+          <div class="bg-surface-container-lowest rounded-xl p-8 text-center">
+            <span class="material-symbols-outlined text-outline text-4xl">api</span>
+            <p class="text-on-surface-variant mt-4">No API elements detected in this repository.</p>
+          </div>
+          {% endif %}
+        {% endif %}
+      </div>
+      {% endif %}
+
+      <div class="mt-12 pt-8 flex justify-between items-center text-sm text-on-surface-variant">
+        <a href="/" class="flex items-center gap-2 hover:text-primary transition-colors">
+          <span class="material-symbols-outlined text-base">arrow_back</span>
+          Back to DocForge
+        </a>
+        <a href="https://github.com/{{ owner }}/{{ repo }}" target="_blank"
+           class="flex items-center gap-2 hover:text-primary transition-colors">
+          View on GitHub
+          <span class="material-symbols-outlined text-base">open_in_new</span>
+        </a>
+      </div>
+    </div>
+  </main>
+</div>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+mermaid.initialize({ startOnLoad: true, theme: 'neutral', securityLevel: 'loose' });
+
+let _currentTab = '{% if data.readme %}readme{% elif data.architecture %}architecture{% else %}api{% endif %}';
+
+// Render README via marked + DOMPurify
+(function renderReadme() {
+  const el = document.getElementById('readme-content');
+  if (!el) return;
+  const raw = {{ (data.readme.readme if data.readme else '') | tojson }};
+  const html = DOMPurify.sanitize(marked.parse(raw));
+  el.setHTML ? el.setHTML(html) : (el.textContent = '', el.insertAdjacentHTML('afterbegin', DOMPurify.sanitize(html)));
+})();
+
+function switchTab(name) {
+  document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
+  const panel = document.getElementById('panel-' + name);
+  if (panel) panel.classList.add('active');
+
+  document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+  const btn = document.getElementById('tab-' + name);
+  if (btn) btn.classList.add('active');
+
+  document.querySelectorAll('.sidebar-link').forEach(l => l.classList.remove('active'));
+  const nav = document.getElementById('nav-' + name);
+  if (nav) nav.classList.add('active');
+
+  _currentTab = name;
+  if (name === 'architecture') mermaid.run({ querySelector: '.mermaid' });
+}
+
+function copyCurrentTab() {
+  let text = '';
+  if (_currentTab === 'readme') {
+    text = {{ (data.readme.readme if data.readme else '') | tojson }};
+  } else if (_currentTab === 'architecture') {
+    text = JSON.stringify({{ (data.architecture or {}) | tojson }}, null, 2);
+  } else if (_currentTab === 'api') {
+    text = JSON.stringify({{ (data.api or {}) | tojson }}, null, 2);
+  }
+  navigator.clipboard.writeText(text).then(() => {
+    const icon = document.getElementById('copy-icon');
+    icon.textContent = 'check';
+    setTimeout(() => { icon.textContent = 'content_copy'; }, 1800);
+  });
+}
+
+function downloadCurrentTab() {
+  window.location.href = '/api/download/{{ owner }}/{{ repo }}/' + _currentTab;
+}
+</script>
+{% endblock %}

app/tools/doc_forge/templates/doc_forge/index.html

@@ -0,0 +1,430 @@
+{% extends "base.html" %}
+
+{% block title %}DocForge — AI Documentation Engine{% endblock %}
+
+{% block extra_head %}
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+{% endblock %}
+
+{% block content %}
+<main class="pt-16 pb-20 overflow-x-hidden">
+
+  {# ── Error Banner ──────────────────────────────────────────────────────────── #}
+  {% if error %}
+  <div class="max-w-7xl mx-auto px-6 pt-6">
+    <div class="flex items-center gap-3 p-4 bg-error-container rounded-xl text-on-error-container text-sm font-medium">
+      <span class="material-symbols-outlined text-error">error</span>
+      {{ error }}
+    </div>
+  </div>
+  {% endif %}
+
+  {# ── Hero ──────────────────────────────────────────────────────────────────── #}
+  <section class="max-w-7xl mx-auto px-6 py-16 lg:py-24 flex flex-col items-center text-center">
+    <div class="mb-4 inline-flex items-center gap-2 px-3 py-1 rounded-full bg-secondary-container text-on-secondary-container text-xs font-semibold tracking-wide">
+      <span class="material-symbols-outlined text-base">auto_awesome</span>
+      AI-POWERED DOCUMENTATION ENGINE
+    </div>
+    <h1 class="text-5xl lg:text-7xl font-extrabold tracking-tighter text-on-surface mb-6 max-w-4xl leading-[1.1]">
+      Document any GitHub repo
+      <span class="bg-gradient-to-r from-primary to-primary-container bg-clip-text text-transparent">instantly.</span>
+    </h1>
+    <p class="text-lg text-on-surface-variant max-w-2xl mb-12 font-medium">
+      Transform complex codebases into human-readable READMEs, architecture maps, and API references in seconds. Just paste a URL.
+    </p>
+
+    {# ── URL Input ─────────────────────────────────────────────────────────────── #}
+    <div id="url-cluster" class="w-full max-w-2xl p-2 bg-surface-container-lowest rounded-xl shadow-2xl shadow-primary/5 flex flex-col sm:flex-row gap-2 transition-all focus-within:ring-4 focus-within:ring-primary/10">
+      <div class="flex-1 flex items-center px-4 gap-3">
+        <span class="material-symbols-outlined text-outline">link</span>
+        <input id="repo-url"
+               class="w-full bg-transparent border-none focus:ring-0 font-mono text-sm placeholder:text-outline/50 py-3 outline-none"
+               placeholder="https://github.com/username/repository"
+               type="text"
+               autocomplete="off"/>
+      </div>
+      <button id="analyze-btn"
+              onclick="analyzeRepo()"
+              class="bg-gradient-to-b from-primary to-primary-container text-on-primary px-8 py-3 rounded-lg font-bold text-sm tracking-tight hover:brightness-110 active:scale-[0.98] transition-all shadow-lg shadow-primary/20 flex items-center gap-2 justify-center">
+        <span id="analyze-icon" class="material-symbols-outlined text-base">search</span>
+        <span id="analyze-label">Analyze</span>
+      </button>
+    </div>
+    <div class="mt-6 flex flex-wrap justify-center items-center gap-6 text-xs font-mono text-outline uppercase tracking-widest">
+      <div class="flex items-center gap-2"><span class="material-symbols-outlined text-sm">check_circle</span> No Login Required</div>
+      <div class="flex items-center gap-2"><span class="material-symbols-outlined text-sm">check_circle</span> Instant Results</div>
+      <div class="flex items-center gap-2"><span class="material-symbols-outlined text-sm">check_circle</span> Free &amp; Open Source</div>
+    </div>
+
+    {# ── Repo Preview Card (hidden until analyze) ──────────────────────────────── #}
+    <div id="repo-card" class="hidden w-full max-w-2xl mt-8 bg-surface-container-lowest rounded-xl p-6 text-left shadow-sm">
+      <div class="flex items-start justify-between gap-4 mb-6">
+        <div>
+          <a id="rc-link" href="#" target="_blank" class="text-xl font-bold text-on-surface hover:text-primary transition-colors font-mono"><span id="rc-name"></span></a>
+          <p id="rc-desc" class="text-sm text-on-surface-variant mt-1 leading-relaxed"></p>
+        </div>
+        <div id="rc-lang-badge" class="px-2 py-1 rounded bg-secondary-container text-on-secondary-container text-xs font-mono whitespace-nowrap"></div>
+      </div>
+      <div class="flex items-center gap-6 text-sm text-on-surface-variant mb-6">
+        <span class="flex items-center gap-1.5"><span class="material-symbols-outlined text-base">star</span> <span id="rc-stars"></span></span>
+        <span class="flex items-center gap-1.5"><span class="material-symbols-outlined text-base">fork_right</span> <span id="rc-forks"></span></span>
+        <span class="flex items-center gap-1.5"><span class="material-symbols-outlined text-base">folder</span> <span id="rc-files"></span> files</span>
+      </div>
+
+      {# Doc type checkboxes #}
+      <p class="text-xs font-bold uppercase tracking-widest text-on-surface-variant mb-3">Generate</p>
+      <div class="flex gap-3 mb-6 flex-wrap">
+        <label class="flex items-center gap-2 px-4 py-2 rounded-lg bg-surface-container cursor-pointer hover:bg-surface-container-high transition-colors text-sm font-medium">
+          <input type="checkbox" id="chk-readme" checked class="accent-primary rounded"> README
+        </label>
+        <label class="flex items-center gap-2 px-4 py-2 rounded-lg bg-surface-container cursor-pointer hover:bg-surface-container-high transition-colors text-sm font-medium">
+          <input type="checkbox" id="chk-architecture" checked class="accent-primary rounded"> Architecture
+        </label>
+        <label class="flex items-center gap-2 px-4 py-2 rounded-lg bg-surface-container cursor-pointer hover:bg-surface-container-high transition-colors text-sm font-medium">
+          <input type="checkbox" id="chk-api" checked class="accent-primary rounded"> API Docs
+        </label>
+      </div>
+
+      <button id="generate-btn"
+              onclick="generateDocs()"
+              class="w-full bg-gradient-to-b from-primary to-primary-container text-on-primary py-3 rounded-lg font-bold text-sm tracking-tight hover:brightness-110 active:scale-[0.98] transition-all shadow-lg shadow-primary/20 flex items-center justify-center gap-2">
+        <span class="material-symbols-outlined text-base">auto_awesome</span>
+        Generate Documentation
+      </button>
+    </div>
+
+    {# ── Progress indicator (hidden until generating) ─────────────────────────── #}
+    <div id="progress-card" class="hidden w-full max-w-2xl mt-8 bg-surface-container-lowest rounded-xl p-8 text-center">
+      <div class="flex flex-col items-center gap-4">
+        <div class="w-12 h-12 rounded-xl bg-primary-fixed flex items-center justify-center animate-pulse">
+          <span class="material-symbols-outlined text-primary text-2xl">psychology</span>
+        </div>
+        <p class="font-bold text-on-surface">Analyzing codebase…</p>
+        <p id="progress-msg" class="text-sm text-on-surface-variant font-mono">Fetching repository structure</p>
+        <div class="w-full bg-surface-container-high rounded-full h-1.5 overflow-hidden">
+          <div id="progress-bar" class="h-full bg-gradient-to-r from-primary to-primary-container rounded-full transition-all duration-500" style="width: 0%"></div>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  {# ── Bento: Features ──────────────────────────────────────────────────────── #}
+  <section class="max-w-7xl mx-auto px-6 py-12">
+    <div class="grid grid-cols-1 md:grid-cols-3 grid-rows-2 gap-4 md:h-[560px]">
+
+      {# Main card #}
+      <div class="md:col-span-2 md:row-span-2 bg-surface-container-lowest p-10 rounded-xl relative overflow-hidden group">
+        <div class="relative z-10 h-full flex flex-col">
+          <div class="w-12 h-12 bg-primary-fixed rounded-lg flex items-center justify-center mb-6">
+            <span class="material-symbols-outlined text-primary">psychology</span>
+          </div>
+          <h3 class="text-3xl font-bold tracking-tight mb-4 text-on-surface">Understand any codebase in seconds.</h3>
+          <p class="text-on-surface-variant max-w-sm mb-8 font-medium">
+            DocForge parses file trees, function relationships, and logic flows to explain
+            <span class="italic text-on-surface">why</span> code works — not just what it does.
+          </p>
+          <div class="mt-auto pt-8 flex items-center justify-between">
+            <div class="flex items-center gap-2 text-xs font-mono text-outline">
+              <span class="material-symbols-outlined text-sm">token</span>
+              Multi-provider AI backbone
+            </div>
+          </div>
+        </div>
+        <div class="absolute right-0 bottom-0 w-2/3 h-2/3 opacity-30 group-hover:opacity-50 transition-opacity">
+          <div class="bg-gradient-to-br from-primary/20 to-transparent w-full h-full rounded-tl-[100px]"></div>
+        </div>
+        <div class="absolute top-10 right-10 flex flex-col gap-2 scale-75 opacity-40 group-hover:opacity-90 transition-all group-hover:scale-100 origin-top-right">
+          <div class="bg-surface-container-highest px-3 py-1.5 rounded-lg text-[10px] font-mono">PARSING TREE... [DONE]</div>
+          <div class="bg-surface-container-highest px-3 py-1.5 rounded-lg text-[10px] font-mono">MAPPING DEPS... [DONE]</div>
+          <div class="bg-surface-container-highest px-3 py-1.5 rounded-lg text-[10px] font-mono">GENERATING DOCS... [OK]</div>
+        </div>
+      </div>
+
+      {# Architecture card #}
+      <div class="bg-surface-container-low p-8 rounded-xl flex flex-col justify-between">
+        <div>
+          <div class="w-10 h-10 bg-tertiary-fixed rounded-lg flex items-center justify-center mb-4">
+            <span class="material-symbols-outlined text-tertiary">account_tree</span>
+          </div>
+          <h4 class="text-xl font-bold tracking-tight mb-2">Visual Architecture Maps.</h4>
+          <p class="text-sm text-on-surface-variant leading-relaxed">
+            Auto-generated Mermaid diagrams show how data flows through the system.
+          </p>
+        </div>
+        <div class="mt-6 p-3 bg-surface-container-lowest rounded-lg flex items-center gap-3">
+          <span class="material-symbols-outlined text-primary text-sm">schema</span>
+          <span class="text-[10px] font-mono uppercase tracking-widest text-outline">Mermaid · Flowchart · ER</span>
+        </div>
+      </div>
+
+      {# Export card #}
+      <div class="bg-inverse-surface p-8 rounded-xl flex flex-col justify-between">
+        <div>
+          <div class="w-10 h-10 bg-slate-700 rounded-lg flex items-center justify-center mb-4">
+            <span class="material-symbols-outlined text-white">data_object</span>
+          </div>
+          <h4 class="text-xl font-bold tracking-tight text-white mb-2">Export Ready.</h4>
+          <p class="text-sm text-slate-400 leading-relaxed">
+            Download README.md, architecture.json, or api.json directly to your project.
+          </p>
+        </div>
+        <div class="mt-4 flex gap-2 items-center">
+          <div class="flex-1 h-1 bg-slate-700 rounded-full overflow-hidden">
+            <div class="w-[85%] h-full bg-primary rounded-full"></div>
+          </div>
+          <span class="text-[10px] font-mono text-slate-500">MD · JSON</span>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  {# ── Feature Spotlight ────────────────────────────────────────────────────── #}
+  <section class="max-w-7xl mx-auto px-6 py-20">
+    <div class="flex flex-col lg:flex-row items-center gap-16">
+      <div class="w-full lg:w-1/2">
+        <h2 class="text-4xl font-extrabold tracking-tighter mb-6 text-on-surface">The complete technical ledger for any project.</h2>
+        <div class="space-y-8">
+          <div class="flex gap-4">
+            <div class="flex-shrink-0 w-6 h-6 rounded-full bg-primary/10 flex items-center justify-center">
+              <span class="material-symbols-outlined text-sm text-primary">description</span>
+            </div>
+            <div>
+              <h5 class="font-bold text-on-surface">AI-Written README</h5>
+              <p class="text-sm text-on-surface-variant">A complete, professional README with setup instructions, features, and badges — generated from your code.</p>
+            </div>
+          </div>
+          <div class="flex gap-4">
+            <div class="flex-shrink-0 w-6 h-6 rounded-full bg-primary/10 flex items-center justify-center">
+              <span class="material-symbols-outlined text-sm text-primary">account_tree</span>
+            </div>
+            <div>
+              <h5 class="font-bold text-on-surface">Architecture Blueprint</h5>
+              <p class="text-sm text-on-surface-variant">Component maps, data flow diagrams, and a Mermaid chart you can drop straight into documentation.</p>
+            </div>
+          </div>
+          <div class="flex gap-4">
+            <div class="flex-shrink-0 w-6 h-6 rounded-full bg-primary/10 flex items-center justify-center">
+              <span class="material-symbols-outlined text-sm text-primary">api</span>
+            </div>
+            <div>
+              <h5 class="font-bold text-on-surface">API Reference</h5>
+              <p class="text-sm text-on-surface-variant">Auto-detected endpoints, functions, and classes with parameters and return types documented.</p>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {# Mock doc preview #}
+      <div class="w-full lg:w-1/2 bg-surface-container-low rounded-xl p-4 relative">
+        <div class="bg-surface-container-lowest rounded-lg overflow-hidden shadow-2xl">
+          <div class="bg-inverse-surface px-4 py-2 flex items-center justify-between">
+            <div class="flex gap-1.5">
+              <div class="w-2.5 h-2.5 rounded-full bg-red-500/50"></div>
+              <div class="w-2.5 h-2.5 rounded-full bg-yellow-500/50"></div>
+              <div class="w-2.5 h-2.5 rounded-full bg-green-500/50"></div>
+            </div>
+            <span class="text-[10px] text-slate-500 font-mono">docforge.ai/docs/owner/repo</span>
+          </div>
+          <div class="p-6">
+            <div class="flex items-center gap-3 mb-6">
+              <div class="w-10 h-10 rounded-full bg-primary flex items-center justify-center">
+                <span class="material-symbols-outlined text-white text-xl">auto_stories</span>
+              </div>
+              <div>
+                <h6 class="text-xs font-mono text-outline uppercase tracking-tighter">Documentation Preview</h6>
+                <p class="font-bold text-on-surface">README.md</p>
+              </div>
+            </div>
+            <div class="space-y-3">
+              <div class="h-2 w-[40%] bg-surface-container rounded-full"></div>
+              <div class="h-2 w-[90%] bg-surface-container rounded-full"></div>
+              <div class="h-2 w-[70%] bg-surface-container rounded-full"></div>
+              <div class="pt-4 flex flex-wrap gap-2">
+                <div class="px-2 py-1 rounded bg-secondary-container text-on-secondary-container text-[10px] font-mono">Python</div>
+                <div class="px-2 py-1 rounded bg-tertiary-fixed text-on-tertiary-fixed text-[10px] font-mono">Flask</div>
+                <div class="px-2 py-1 rounded bg-primary-fixed text-on-primary-fixed text-[10px] font-mono">MIT</div>
+              </div>
+            </div>
+          </div>
+        </div>
+        <div class="absolute -z-10 -right-4 -bottom-4 w-full h-full bg-primary/5 rounded-xl blur-3xl"></div>
+      </div>
+    </div>
+  </section>
+
+  {# ── Recent Repos ─────────────────────────────────────────────────────────── #}
+  {% if recent %}
+  <section class="max-w-7xl mx-auto px-6 py-12">
+    <h2 class="text-2xl font-bold tracking-tight text-on-surface mb-8">Recent Repositories</h2>
+    <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+      {% for r in recent %}
+      <a href="/docs/{{ r.owner }}/{{ r.repo }}"
+         class="group block bg-surface-container-lowest p-6 rounded-xl hover:bg-surface-container transition-colors">
+        <div class="flex items-start justify-between mb-3">
+          <div>
+            <p class="font-mono text-xs text-outline mb-1">{{ r.owner }}</p>
+            <h3 class="font-bold text-on-surface group-hover:text-primary transition-colors">{{ r.repo }}</h3>
+          </div>
+          {% if r.info.language %}
+          <span class="px-2 py-0.5 rounded bg-secondary-container text-on-secondary-container text-[10px] font-mono">{{ r.info.language }}</span>
+          {% endif %}
+        </div>
+        {% if r.info.description %}
+        <p class="text-sm text-on-surface-variant line-clamp-2 mb-4">{{ r.info.description }}</p>
+        {% endif %}
+        <div class="flex items-center gap-4 text-xs text-outline">
+          <span class="flex items-center gap-1"><span class="material-symbols-outlined text-sm">star</span> {{ r.info.stars }}</span>
+          <span class="flex items-center gap-1"><span class="material-symbols-outlined text-sm">description</span> {{ r.doc_count }} docs</span>
+        </div>
+      </a>
+      {% endfor %}
+    </div>
+  </section>
+  {% endif %}
+
+  {# ── CTA ──────────────────────────────────────────────────────────────────── #}
+  <section class="max-w-5xl mx-auto px-6 py-20">
+    <div class="bg-surface-container-lowest rounded-xl p-12 lg:p-20 text-center relative overflow-hidden">
+      <div class="absolute top-0 left-0 w-full h-1 bg-gradient-to-r from-primary via-primary-container to-primary"></div>
+      <h2 class="text-4xl font-extrabold tracking-tight mb-4 text-on-surface">Ready to document your code?</h2>
+      <p class="text-on-surface-variant mb-10 max-w-xl mx-auto">Paste any public GitHub URL above and get a full documentation suite in under a minute.</p>
+      <button onclick="document.getElementById('repo-url').focus(); window.scrollTo({top: 0, behavior: 'smooth'})"
+              class="bg-gradient-to-b from-primary to-primary-container text-on-primary px-10 py-4 rounded-lg font-bold text-base shadow-xl shadow-primary/20 hover:scale-105 transition-transform">
+        Get Started Free
+      </button>
+    </div>
+  </section>
+
+</main>
+
+{# ── Footer ───────────────────────────────────────────────────────────────── #}
+<footer class="bg-surface-container-lowest py-12">
+  <div class="max-w-7xl mx-auto px-6 flex flex-col md:flex-row justify-between items-center gap-8">
+    <div class="flex flex-col items-center md:items-start">
+      <span class="text-lg font-bold tracking-tight text-on-surface mb-1">DocForge</span>
+      <p class="text-xs text-outline font-medium">AI-powered documentation for every GitHub repository.</p>
+    </div>
+    <div class="flex gap-8">
+      <a href="https://github.com/Moealsarraj/doc-forge" target="_blank" class="text-sm font-medium text-on-surface-variant hover:text-primary transition-colors">GitHub</a>
+    </div>
+  </div>
+</footer>
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+// CSRF helper
+const _csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+function _post(url, body) {
+  return fetch(url, {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json', 'X-CSRFToken': _csrf},
+    body: JSON.stringify(body)
+  });
+}
+
+// State
+let _currentOwner = null;
+let _currentRepo  = null;
+
+function setProgress(pct, msg) {
+  document.getElementById('progress-bar').style.width = pct + '%';
+  document.getElementById('progress-msg').textContent = msg;
+}
+
+async function analyzeRepo() {
+  const url = document.getElementById('repo-url').value.trim();
+  if (!url) return;
+
+  // Show progress
+  document.getElementById('repo-card').classList.add('hidden');
+  document.getElementById('progress-card').classList.remove('hidden');
+  const btn = document.getElementById('analyze-btn');
+  btn.disabled = true;
+  document.getElementById('analyze-label').textContent = 'Analyzing…';
+  document.getElementById('analyze-icon').textContent = 'hourglass_top';
+  setProgress(10, 'Connecting to GitHub API…');
+
+  try {
+    setProgress(30, 'Fetching repository metadata…');
+    const res  = await _post('/api/analyze', {url});
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || 'Analysis failed');
+
+    setProgress(100, 'Done!');
+    _currentOwner = data.owner;
+    _currentRepo  = data.repo;
+
+    // Populate card
+    const info = data.info;
+    document.getElementById('rc-name').textContent = info.full_name;
+    document.getElementById('rc-link').href = info.url;
+    document.getElementById('rc-desc').textContent = info.description || 'No description provided.';
+    document.getElementById('rc-lang-badge').textContent = info.language || 'Unknown';
+    document.getElementById('rc-stars').textContent = (info.stars || 0).toLocaleString() + ' stars';
+    document.getElementById('rc-forks').textContent = (info.forks || 0).toLocaleString() + ' forks';
+    document.getElementById('rc-files').textContent = data.file_count;
+
+    setTimeout(() => {
+      document.getElementById('progress-card').classList.add('hidden');
+      document.getElementById('repo-card').classList.remove('hidden');
+    }, 400);
+  } catch (err) {
+    document.getElementById('progress-card').classList.add('hidden');
+    alert('Error: ' + err.message);
+  } finally {
+    btn.disabled = false;
+    document.getElementById('analyze-label').textContent = 'Analyze';
+    document.getElementById('analyze-icon').textContent = 'search';
+  }
+}
+
+async function generateDocs() {
+  if (!_currentOwner) return;
+  const url = document.getElementById('repo-url').value.trim();
+  const types = [];
+  if (document.getElementById('chk-readme').checked)       types.push('readme');
+  if (document.getElementById('chk-architecture').checked) types.push('architecture');
+  if (document.getElementById('chk-api').checked)          types.push('api');
+  if (!types.length) { alert('Select at least one doc type.'); return; }
+
+  document.getElementById('repo-card').classList.add('hidden');
+  document.getElementById('progress-card').classList.remove('hidden');
+  setProgress(5, 'Starting AI generation…');
+
+  const steps = [
+    [20, 'Fetching key source files…'],
+    [45, 'Generating README…'],
+    [65, 'Mapping architecture…'],
+    [80, 'Documenting API…'],
+    [92, 'Saving to database…']
+  ];
+  let si = 0;
+  const ticker = setInterval(() => {
+    if (si < steps.length) { setProgress(...steps[si++]); }
+  }, 1800);
+
+  try {
+    const res  = await _post('/api/generate', {url, types});
+    const data = await res.json();
+    clearInterval(ticker);
+    if (!res.ok) throw new Error(data.error || 'Generation failed');
+
+    setProgress(100, 'Complete! Redirecting…');
+    setTimeout(() => {
+      window.location.href = `/docs/${data.owner}/${data.repo}`;
+    }, 600);
+  } catch (err) {
+    clearInterval(ticker);
+    document.getElementById('progress-card').classList.add('hidden');
+    document.getElementById('repo-card').classList.remove('hidden');
+    alert('Error: ' + err.message);
+  }
+}
+
+// Allow Enter key in input
+document.getElementById('repo-url').addEventListener('keydown', e => {
+  if (e.key === 'Enter') analyzeRepo();
+});
+</script>
+{% endblock %}

app/tools/git_narrator/narrator.py

@@ -0,0 +1,112 @@
+"""Git history narrator — turns raw commits into editorial prose."""
+import os
+import re
+import requests
+from app.core.ai import call_ai_json
+
+_GITHUB_API = "https://api.github.com"
+_SYSTEM = """You are a senior engineering writer and technical storyteller.
+You transform dry git commit logs into compelling, editorial-quality engineering narratives.
+Write like a thoughtful tech lead preparing a sprint retrospective for the whole company.
+Be specific about what was built, avoid jargon where plain language works, and surface the human story behind the code.
+Return ONLY valid JSON — no markdown fences."""
+
+_PROMPT_TMPL = """Narrate the following git history into an editorial engineering report.
+
+GIT HISTORY:
+---
+{log}
+---
+
+Return a JSON object with EXACTLY these keys:
+{{
+  "period_label": "<inferred time period, e.g. 'Sprint 42' or 'Week of Jan 15, 2025'>",
+  "highlights": [
+    {{
+      "title": "<punchy title for the biggest story>",
+      "narrative": "<2-3 paragraph editorial story — what changed, why it matters, what comes next>",
+      "key_commit": "<most important commit message verbatim>",
+      "impact": "<one sentence business impact>"
+    }}
+  ],
+  "tech_debt": [
+    {{
+      "icon": "<material symbol name, e.g. cleaning_services|speed|bug_report|tune>",
+      "title": "<short title>",
+      "description": "<2-3 sentences on what was fixed/refactored and the measurable benefit>"
+    }}
+  ],
+  "milestones": [
+    {{
+      "status": "<shipped|in_progress|planned>",
+      "title": "<milestone name>",
+      "narrative": "<editorial paragraph on this milestone>",
+      "contributors": ["<name or handle>"]
+    }}
+  ],
+  "commits": [
+    {{
+      "hash": "<7-char hash or empty string>",
+      "message": "<commit message>",
+      "author": "<author name or handle>",
+      "time": "<relative time e.g. '2 hours ago'>",
+      "type": "<feat|fix|docs|refactor|chore|test|perf>"
+    }}
+  ],
+  "summary_stats": {{
+    "total_commits": <integer>,
+    "contributors": <integer>,
+    "features": <integer>,
+    "fixes": <integer>
+  }}
+}}
+
+Aim for 2-3 highlights, 2-3 tech_debt items, 2-3 milestones.
+If the log is sparse, extrapolate intelligently from what's there.
+commits should list ALL commits from the log (max 20)."""
+
+
+def _fetch_github_commits(owner: str, repo: str, limit: int = 30) -> str:
+    """Fetch recent commits from GitHub and format as git log text."""
+    token = os.environ.get("GITHUB_TOKEN", "")
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    r = requests.get(f"{_GITHUB_API}/repos/{owner}/{repo}/commits?per_page={limit}",
+                     headers=headers, timeout=20)
+    r.raise_for_status()
+    lines = []
+    for c in r.json():
+        sha   = c["sha"][:7]
+        msg   = c["commit"]["message"].split("\n")[0]
+        name  = c["commit"]["author"]["name"]
+        date  = c["commit"]["author"]["date"]
+        lines.append(f"commit {sha}\nAuthor: {name}\nDate:   {date}\n\n    {msg}\n")
+    return "\n".join(lines)
+
+
+def _parse_github_url(text: str):
+    """Return (owner, repo) if text looks like a GitHub URL, else None."""
+    m = re.search(r"github\.com/([^/\s]+)/([^/\s]+?)(?:\.git)?(?:\s|$)", text)
+    if m:
+        return m.group(1), m.group(2)
+    parts = text.strip().split("/")
+    if len(parts) == 2 and " " not in text:
+        return parts[0], parts[1]
+    return None
+
+
+def narrate(raw_input: str) -> dict:
+    """Narrate a git history. raw_input can be a GitHub URL or raw git log text."""
+    parsed = _parse_github_url(raw_input.strip())
+    if parsed:
+        try:
+            owner, repo = parsed
+            log = _fetch_github_commits(owner, repo)
+        except Exception as e:
+            log = raw_input  # fallback to treating as raw log
+    else:
+        log = raw_input
+
+    prompt = _PROMPT_TMPL.format(log=log[:8000])
+    return call_ai_json([{"role": "user", "content": prompt}], system=_SYSTEM) or {}

app/tools/git_narrator/routes.py

@@ -0,0 +1,22 @@
+"""Git Narrator routes."""
+from flask import Blueprint, render_template, request, jsonify
+from .narrator import narrate
+
+bp = Blueprint("git_narrator", __name__, template_folder="templates")
+
+
+@bp.route("/")
+def index():
+    return render_template("git_narrator/index.html")
+
+
+@bp.route("/api/narrate", methods=["POST"])
+def api_narrate():
+    body = request.get_json(silent=True) or {}
+    raw  = (body.get("content") or "").strip()
+    if not raw:
+        return jsonify({"error": "content is required (GitHub URL or git log text)"}), 400
+    if len(raw) < 10:
+        return jsonify({"error": "Input too short — paste a URL or git log"}), 400
+    result = narrate(raw)
+    return jsonify(result)

app/tools/git_narrator/templates/git_narrator/index.html

@@ -0,0 +1,509 @@
+{% extends "base.html" %}
+{% block title %}Git Narrator — Engineering Stories{% endblock %}
+
+{% block content %}
+
+{# ── Toolbar ─────────────────────────────────────────────────────────────────── #}
+<header class="toolbar-blur fixed top-0 w-full z-50 flex items-center justify-between px-5 h-12 flex-shrink-0"
+        style="border-bottom:1px solid rgba(240,246,252,0.08);">
+  <div class="flex items-center gap-3">
+    <div class="flex items-center gap-2">
+      <span class="material-symbols-outlined text-[16px]" style="color:#58A6FF;">auto_stories</span>
+      <span class="font-semibold text-gd-text text-sm" style="letter-spacing:-0.02em;">Git Narrator</span>
+    </div>
+    <span style="color:rgba(240,246,252,0.12);">|</span>
+    <span class="section-label" style="color:#484F58;">Engineering Stories</span>
+  </div>
+  <div class="flex items-center gap-2">
+    <span id="period-chip" class="hidden pill" style="background:rgba(88,166,255,0.12); color:#58A6FF;"></span>
+    <button id="copy-btn" class="hidden btn-ghost text-xs">
+      <span id="copy-icon" class="material-symbols-outlined text-[13px]">content_copy</span>
+      Copy
+    </button>
+    <button id="narrate-btn" onclick="doNarrate()" class="btn-primary">
+      <span class="material-symbols-outlined text-[14px]">auto_awesome</span>
+      <span id="narrate-label">Narrate History</span>
+    </button>
+  </div>
+</header>
+
+{# ── Body ─────────────────────────────────────────────────────────────────────── #}
+<div class="flex flex-1 pt-12 overflow-hidden">
+
+  {# ── Left: Terminal input zone ───────────────────────────────────────────────── #}
+  <aside class="w-[320px] flex-shrink-0 flex flex-col overflow-y-auto"
+         style="background:#0D1117; border-right:1px solid rgba(240,246,252,0.07);">
+
+    {# Panel label #}
+    <div class="flex items-center gap-2 px-4 py-3"
+         style="border-bottom:1px solid rgba(240,246,252,0.06);">
+      <span class="w-1.5 h-1.5 rounded-full" style="background:#3FB950;"></span>
+      <span class="section-label">Source</span>
+    </div>
+
+    {# Prompt hint #}
+    <div class="px-4 pt-3 pb-1.5 flex items-center gap-2">
+      <span class="text-[11px] font-mono" style="color:#3FB950;">$</span>
+      <span class="text-[10px] font-mono" style="color:#484F58;">paste url or git log below</span>
+    </div>
+
+    {# Input area #}
+    <div class="px-3 pb-3">
+      <div class="rounded-lg overflow-hidden"
+           style="background:#161B22; border:1px solid rgba(240,246,252,0.08);
+                  box-shadow:inset 0 2px 8px rgba(0,0,0,0.3);">
+        <textarea id="log-input" class="input-terminal" style="height:200px;"
+                  placeholder="https://github.com/org/repo&#10;&#10;# or raw git log:&#10;a3f1b2c feat: add OAuth2 login&#10;d4e5f6a fix: resolve race condition&#10;7b8c9d0 docs: update API reference&#10;…"></textarea>
+      </div>
+    </div>
+
+    {# Run button #}
+    <div class="px-3 pb-4">
+      <button onclick="doNarrate()"
+              class="w-full flex items-center justify-center gap-2 py-2.5 rounded-lg font-mono text-[11px] font-semibold transition-all"
+              style="background:#238636; color:#fff; border:1px solid rgba(63,185,80,0.3); box-shadow:0 1px 4px rgba(0,0,0,0.4);">
+        <span class="material-symbols-outlined text-[14px]">auto_awesome</span>
+        narrate_history()
+      </button>
+    </div>
+
+    {# Divider #}
+    <div style="height:1px; background:rgba(240,246,252,0.06);"></div>
+
+    {# Stats #}
+    <div id="stats-area" class="hidden flex flex-col gap-2.5 px-3 pt-3">
+      <div class="flex items-center gap-1.5 px-1">
+        <span class="text-[11px] font-mono" style="color:#3FB950;">$</span>
+        <span class="section-label">git shortlog -sn</span>
+      </div>
+      <div class="grid grid-cols-2 gap-1.5">
+        <div class="rounded-lg p-3 text-center" style="background:#161B22; border:1px solid rgba(240,246,252,0.06);">
+          <p id="stat-commits" class="text-lg font-bold font-mono" style="color:#58A6FF;">—</p>
+          <p class="section-label mt-0.5">Commits</p>
+        </div>
+        <div class="rounded-lg p-3 text-center" style="background:#161B22; border:1px solid rgba(240,246,252,0.06);">
+          <p id="stat-contributors" class="text-lg font-bold font-mono" style="color:#3FB950;">—</p>
+          <p class="section-label mt-0.5">Authors</p>
+        </div>
+        <div class="rounded-lg p-3 text-center" style="background:#161B22; border:1px solid rgba(240,246,252,0.06);">
+          <p id="stat-features" class="text-lg font-bold font-mono" style="color:#D2A8FF;">—</p>
+          <p class="section-label mt-0.5">Features</p>
+        </div>
+        <div class="rounded-lg p-3 text-center" style="background:#161B22; border:1px solid rgba(240,246,252,0.06);">
+          <p id="stat-fixes" class="text-lg font-bold font-mono" style="color:#E3B341;">—</p>
+          <p class="section-label mt-0.5">Fixes</p>
+        </div>
+      </div>
+    </div>
+
+    {# Commits log #}
+    <div id="commits-area" class="hidden flex flex-col gap-1 px-3 pt-3 pb-4">
+      <div class="flex items-center gap-1.5 px-1 mb-1">
+        <span class="text-[11px] font-mono" style="color:#3FB950;">$</span>
+        <span class="section-label">git log --oneline</span>
+      </div>
+      <div id="commits-list" class="flex flex-col"></div>
+    </div>
+
+  </aside>
+
+  {# ── Right: Narrative output ─────────────────────────────────────────────────── #}
+  <main class="flex-1 overflow-y-auto" style="background:#161B22;">
+
+    {# Empty state #}
+    <div id="empty-state" class="h-full flex flex-col items-center justify-center text-center select-none px-8">
+      <div class="w-14 h-14 rounded-2xl flex items-center justify-center mb-5"
+           style="background:#1C2128; border:1px solid rgba(240,246,252,0.08);">
+        <span class="material-symbols-outlined text-2xl" style="color:#484F58;">auto_stories</span>
+      </div>
+      <p class="text-sm font-semibold text-gd-text mb-2" style="letter-spacing:-0.02em;">The Narrative</p>
+      <p class="text-xs text-gd-text-2 max-w-xs leading-relaxed">
+        Paste a GitHub URL or git log on the left. The AI writes your commit history as an editorial engineering report.
+      </p>
+      <div class="mt-5 flex flex-wrap justify-center gap-1.5">
+        {% for tag in ['Highlights', 'Tech Debt', 'Milestones', 'Contributors', 'Impact'] %}
+        <span class="pill" style="background:#1C2128; color:#484F58; border:1px solid rgba(240,246,252,0.06); font-size:9px;">{{ tag }}</span>
+        {% endfor %}
+      </div>
+    </div>
+
+    {# Loading state #}
+    <div id="loading-state" class="hidden h-full flex flex-col items-center justify-center text-center px-8">
+      <div class="w-14 h-14 rounded-2xl flex items-center justify-center mb-5"
+           style="background:rgba(88,166,255,0.08); border:1px solid rgba(88,166,255,0.15);">
+        <span class="material-symbols-outlined text-2xl" style="color:#58A6FF; animation:pulse 1.4s ease-in-out infinite;">psychology</span>
+      </div>
+      <p class="text-sm font-semibold text-gd-text mb-1.5" style="letter-spacing:-0.02em;">Writing the narrative…</p>
+      <p id="loading-msg" class="text-xs font-mono text-gd-text-3">Parsing commit history</p>
+      <div class="w-48 h-0.5 rounded-full overflow-hidden mt-5"
+           style="background:rgba(240,246,252,0.06);">
+        <div id="loading-bar" class="h-full rounded-full transition-all duration-700"
+             style="width:5%; background:#58A6FF;"></div>
+      </div>
+    </div>
+
+    {# Narrative output #}
+    <div id="narrative-output" class="hidden max-w-2xl mx-auto px-8 py-8 flex flex-col gap-10 pb-12">
+
+      {# Report header #}
+      <div class="flex items-end justify-between">
+        <div>
+          <p class="section-label mb-2">Engineering Report</p>
+          <h1 class="text-2xl font-bold text-gd-text" style="letter-spacing:-0.03em;">The Narrative</h1>
+        </div>
+        <span id="period-label-inline" class="text-xs font-mono text-gd-text-3 pb-1"></span>
+      </div>
+
+      <div style="height:1px; background:rgba(240,246,252,0.07);"></div>
+
+      <div id="highlights-section"></div>
+      <div id="tech-debt-section"></div>
+      <div id="milestones-section"></div>
+
+    </div>
+  </main>
+</div>
+
+{# ── Footer ─────────────────────────────────────────────────────────────────── #}
+<footer class="toolbar-blur fixed bottom-0 w-full h-9 flex items-center justify-between px-5 flex-shrink-0"
+        style="border-top:1px solid rgba(240,246,252,0.07);">
+  <span class="section-label">Git Narrator v1.0</span>
+  <div class="flex items-center gap-1.5">
+    <span id="footer-dot" class="w-1.5 h-1.5 rounded-full" style="background:#3FB950;"></span>
+    <span id="footer-status" class="section-label" style="color:#3FB950;">Ready</span>
+  </div>
+</footer>
+
+<style>
+@keyframes pulse { 0%,100%{opacity:1} 50%{opacity:0.4} }
+</style>
+
+{% endblock %}
+
+{% block extra_scripts %}
+<script>
+const _csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+let _narrativeText = '';
+
+function setStatus(msg, color='#3FB950') {
+  document.getElementById('footer-dot').style.background = color;
+  document.getElementById('footer-status').style.color = color;
+  document.getElementById('footer-status').textContent = msg;
+}
+
+async function doNarrate() {
+  const raw = document.getElementById('log-input').value.trim();
+  if (!raw) { document.getElementById('log-input').focus(); return; }
+
+  document.getElementById('empty-state').classList.add('hidden');
+  document.getElementById('narrative-output').classList.add('hidden');
+  document.getElementById('loading-state').classList.remove('hidden');
+  document.getElementById('stats-area').classList.add('hidden');
+  document.getElementById('commits-area').classList.add('hidden');
+  document.getElementById('copy-btn').classList.add('hidden');
+  document.getElementById('period-chip').classList.add('hidden');
+
+  const btn = document.getElementById('narrate-btn');
+  btn.disabled = true;
+  document.getElementById('narrate-label').textContent = 'Writing…';
+  setStatus('Processing…', '#E3B341');
+
+  let pct = 5;
+  const msgs = ['Parsing commit history…','Identifying key themes…','Writing highlights…','Building the narrative…'];
+  let mi = 0;
+  const ticker = setInterval(() => {
+    pct = Math.min(pct + 12, 88);
+    document.getElementById('loading-bar').style.width = pct + '%';
+    document.getElementById('loading-msg').textContent = msgs[mi++ % msgs.length];
+  }, 1400);
+
+  try {
+    const res  = await fetch('/api/narrate', {
+      method:  'POST',
+      headers: {'Content-Type':'application/json','X-CSRFToken':_csrf},
+      body:    JSON.stringify({content: raw})
+    });
+    const data = await res.json();
+    clearInterval(ticker);
+    document.getElementById('loading-bar').style.width = '100%';
+    if (!res.ok) throw new Error(data.error || 'Narration failed');
+    renderNarrative(data);
+    setStatus('Done');
+  } catch(err) {
+    clearInterval(ticker);
+    document.getElementById('loading-state').classList.add('hidden');
+    document.getElementById('empty-state').classList.remove('hidden');
+    setStatus('Error', '#F85149');
+    alert('Error: ' + err.message);
+  } finally {
+    btn.disabled = false;
+    document.getElementById('narrate-label').textContent = 'Narrate History';
+  }
+}
+
+function renderNarrative(data) {
+  document.getElementById('loading-state').classList.add('hidden');
+
+  const periodText = data.period_label || '';
+  document.getElementById('period-chip').textContent = periodText;
+  document.getElementById('period-chip').classList.toggle('hidden', !periodText);
+  document.getElementById('period-label-inline').textContent = periodText;
+
+  // Stats
+  const ss = data.summary_stats || {};
+  document.getElementById('stat-commits').textContent      = ss.total_commits || '—';
+  document.getElementById('stat-contributors').textContent = ss.contributors  || '—';
+  document.getElementById('stat-features').textContent     = ss.features      || '—';
+  document.getElementById('stat-fixes').textContent        = ss.fixes         || '—';
+  document.getElementById('stats-area').classList.remove('hidden');
+
+  // Commits
+  const cl = document.getElementById('commits-list');
+  while (cl.firstChild) cl.removeChild(cl.firstChild);
+  (data.commits || []).slice(0, 8).forEach(c => {
+    const row = document.createElement('div');
+    row.className = 'flex items-start gap-2 py-1.5 font-mono';
+    row.style.cssText = 'border-bottom:1px solid rgba(240,246,252,0.04);';
+
+    const hash = document.createElement('span');
+    hash.className = 'text-[10px] flex-shrink-0 mt-0.5';
+    hash.style.color = '#58A6FF';
+    hash.textContent = (c.hash || '???????').slice(0, 7);
+
+    const info = document.createElement('div');
+    info.className = 'min-w-0';
+    const msg = document.createElement('p');
+    msg.className = 'text-[11px] truncate';
+    msg.style.color = '#C9D1D9';
+    msg.textContent = c.message || '';
+    const meta = document.createElement('p');
+    meta.className = 'text-[9px] mt-0.5';
+    meta.style.color = '#484F58';
+    meta.textContent = [c.time, c.author ? '@'+c.author : ''].filter(Boolean).join(' · ');
+    info.append(msg, meta);
+    row.append(hash, info);
+    cl.appendChild(row);
+  });
+  document.getElementById('commits-area').classList.remove('hidden');
+
+  // ── Highlights ─────────────────────────────────────────────────────────────
+  const hs = document.getElementById('highlights-section');
+  while (hs.firstChild) hs.removeChild(hs.firstChild);
+  if ((data.highlights || []).length) {
+    hs.appendChild(makeSectionHeader("Week's Highlights", 'auto_awesome', '#58A6FF'));
+    const grid = document.createElement('div');
+    grid.className = 'flex flex-col gap-3 mt-4';
+
+    (data.highlights || []).forEach(h => {
+      const card = document.createElement('div');
+      card.className = 'card p-5';
+      card.style.borderLeftColor = '#58A6FF';
+      card.style.borderLeftWidth = '3px';
+
+      const title = document.createElement('h3');
+      title.className = 'text-sm font-semibold text-gd-text mb-2';
+      title.style.letterSpacing = '-0.01em';
+      title.textContent = h.title || '';
+
+      const narrative = document.createElement('p');
+      narrative.className = 'text-xs leading-relaxed text-gd-text-2';
+      narrative.textContent = h.narrative || '';
+
+      card.append(title, narrative);
+
+      if (h.impact) {
+        const impact = document.createElement('div');
+        impact.className = 'flex items-center gap-1.5 mt-3';
+        const icon = document.createElement('span');
+        icon.className = 'material-symbols-outlined text-[13px]';
+        icon.style.color = '#3FB950';
+        icon.textContent = 'trending_up';
+        const txt = document.createElement('span');
+        txt.className = 'text-[11px] font-medium';
+        txt.style.color = '#3FB950';
+        txt.textContent = h.impact;
+        impact.append(icon, txt);
+        card.appendChild(impact);
+      }
+
+      if (h.key_commit) {
+        const pre = document.createElement('pre');
+        pre.className = 'font-mono text-[10px] leading-relaxed whitespace-pre-wrap mt-3 p-3 rounded-lg';
+        pre.style.cssText = 'background:#0D1117; color:#484F58; border:1px solid rgba(240,246,252,0.06);';
+        pre.textContent = h.key_commit;
+        card.appendChild(pre);
+      }
+
+      grid.appendChild(card);
+    });
+    hs.appendChild(grid);
+  }
+
+  // ── Tech Debt ──────────────────────────────────────────────────────────────
+  const td = document.getElementById('tech-debt-section');
+  while (td.firstChild) td.removeChild(td.firstChild);
+  if ((data.tech_debt || []).length) {
+    td.appendChild(makeSectionHeader('Technical Debt Addressed', 'build', '#E3B341'));
+    const grid = document.createElement('div');
+    grid.className = 'grid grid-cols-2 gap-3 mt-4';
+
+    (data.tech_debt || []).forEach(item => {
+      const card = document.createElement('div');
+      card.className = 'card p-4';
+
+      const top = document.createElement('div');
+      top.className = 'flex items-center gap-2 mb-2';
+      const icon = document.createElement('span');
+      icon.className = 'material-symbols-outlined text-[15px]';
+      icon.style.color = '#E3B341';
+      icon.textContent = item.icon || 'build';
+      const h4 = document.createElement('p');
+      h4.className = 'text-xs font-semibold text-gd-text';
+      h4.textContent = item.title || '';
+      top.append(icon, h4);
+
+      const desc = document.createElement('p');
+      desc.className = 'text-xs leading-relaxed text-gd-text-2';
+      desc.textContent = item.description || '';
+
+      card.append(top, desc);
+      grid.appendChild(card);
+    });
+    td.appendChild(grid);
+  }
+
+  // ── Milestones ─────────────────────────────────────────────────────────────
+  const ms = document.getElementById('milestones-section');
+  while (ms.firstChild) ms.removeChild(ms.firstChild);
+  if ((data.milestones || []).length) {
+    ms.appendChild(makeSectionHeader('Feature Milestones', 'flag', '#58A6FF'));
+
+    const timeline = document.createElement('div');
+    timeline.className = 'relative pl-8 flex flex-col gap-6 mt-4';
+    const line = document.createElement('div');
+    line.className = 'absolute left-[9px] top-2 bottom-2 w-px';
+    line.style.background = 'rgba(240,246,252,0.08)';
+    timeline.appendChild(line);
+
+    (data.milestones || []).forEach(m => {
+      const row = document.createElement('div');
+      row.className = 'relative';
+
+      const dot = document.createElement('div');
+      dot.className = 'absolute -left-[28px] top-1.5 w-4 h-4 rounded-full flex items-center justify-center flex-shrink-0';
+      if (m.status === 'shipped') {
+        dot.style.cssText = 'background:#238636; border:1px solid rgba(63,185,80,0.4);';
+        const chk = document.createElement('span');
+        chk.className = 'material-symbols-outlined';
+        chk.style.cssText = 'font-size:10px; color:#fff; font-variation-settings:"FILL" 1,"wght" 600,"GRAD" 0,"opsz" 20;';
+        chk.textContent = 'check';
+        dot.appendChild(chk);
+      } else {
+        dot.style.cssText = 'background:#1C2128; border:2px solid #58A6FF;';
+        const pulse = document.createElement('div');
+        pulse.className = 'w-1.5 h-1.5 rounded-full';
+        pulse.style.cssText = 'background:#58A6FF; animation:pulse 1.4s ease-in-out infinite;';
+        dot.appendChild(pulse);
+      }
+
+      const card = document.createElement('div');
+      card.className = 'card p-5';
+
+      const badge = document.createElement('span');
+      badge.className = 'pill mb-3 inline-flex';
+      badge.style.cssText = m.status === 'shipped'
+        ? 'background:rgba(63,185,80,0.10); color:#3FB950;'
+        : 'background:rgba(88,166,255,0.10); color:#58A6FF;';
+      badge.textContent = (m.status || 'planned').toUpperCase();
+
+      const h4 = document.createElement('h4');
+      h4.className = 'text-sm font-semibold text-gd-text mb-2';
+      h4.style.letterSpacing = '-0.01em';
+      h4.textContent = m.title || '';
+
+      const p = document.createElement('p');
+      p.className = 'text-xs leading-relaxed text-gd-text-2';
+      p.textContent = m.narrative || '';
+
+      card.append(badge, h4, p);
+
+      if (m.contributors && m.contributors.length) {
+        const contrib = document.createElement('div');
+        contrib.className = 'flex items-center gap-2 mt-3 pt-3';
+        contrib.style.cssText = 'border-top:1px solid rgba(240,246,252,0.07);';
+        const avatars = document.createElement('div');
+        avatars.className = 'flex -space-x-1';
+        m.contributors.slice(0, 4).forEach(name => {
+          const av = document.createElement('div');
+          av.className = 'w-5 h-5 rounded-full flex items-center justify-center text-[8px] font-bold font-mono';
+          av.style.cssText = 'background:#238636; color:#fff; border:2px solid #1C2128;';
+          av.textContent = (name[0] || '?').toUpperCase();
+          avatars.appendChild(av);
+        });
+        const names = document.createElement('span');
+        names.className = 'text-[10px] text-gd-text-3';
+        names.textContent = m.contributors.join(', ');
+        contrib.append(avatars, names);
+        card.appendChild(contrib);
+      }
+
+      row.append(dot, card);
+      timeline.appendChild(row);
+    });
+    ms.appendChild(timeline);
+  }
+
+  _narrativeText = buildCopyText(data);
+  const copyBtn = document.getElementById('copy-btn');
+  copyBtn.classList.remove('hidden');
+  copyBtn.onclick = () => {
+    navigator.clipboard.writeText(_narrativeText).then(() => {
+      const icon = document.getElementById('copy-icon');
+      icon.textContent = 'check';
+      setTimeout(() => { icon.textContent = 'content_copy'; }, 2000);
+    });
+  };
+
+  document.getElementById('narrative-output').classList.remove('hidden');
+  document.getElementById('narrative-output').scrollIntoView({ behavior:'smooth' });
+}
+
+function makeSectionHeader(title, iconName, color) {
+  const wrap = document.createElement('div');
+  wrap.className = 'section-header';
+  const icon = document.createElement('span');
+  icon.className = 'material-symbols-outlined text-[15px]';
+  icon.style.color = color;
+  icon.textContent = iconName;
+  const h = document.createElement('h2');
+  h.className = 'text-sm font-semibold text-gd-text';
+  h.style.letterSpacing = '-0.01em';
+  h.textContent = title;
+  const line = document.createElement('div');
+  line.className = 'section-header-line';
+  wrap.append(icon, h, line);
+  return wrap;
+}
+
+function buildCopyText(data) {
+  const lines = ['# ' + (data.period_label || 'Engineering Narrative') + '\n'];
+  (data.highlights || []).forEach(h => {
+    lines.push('## ' + h.title + '\n' + h.narrative + '\n');
+    if (h.impact) lines.push('Impact: ' + h.impact + '\n');
+  });
+  if ((data.tech_debt || []).length) {
+    lines.push('## Technical Debt\n');
+    data.tech_debt.forEach(t => lines.push('### ' + t.title + '\n' + t.description + '\n'));
+  }
+  if ((data.milestones || []).length) {
+    lines.push('## Milestones\n');
+    data.milestones.forEach(m => lines.push('[' + (m.status||'').toUpperCase() + '] ' + m.title + '\n' + m.narrative + '\n'));
+  }
+  return lines.join('\n');
+}
+
+document.addEventListener('keydown', e => {
+  if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') doNarrate();
+});
+</script>
+{% endblock %}

app/tools/schema_detective/detective.py

@@ -0,0 +1,252 @@
+"""Schema Detective — audits database schemas for design issues."""
+import re
+from app.core.ai import call_ai_json, call_ai
+
+_SYSTEM = """You are a senior database architect and security engineer with deep expertise in SQL,
+normalization, indexing strategies, database security, and production reliability.
+You audit schemas with a critical eye — catching design flaws, security vulnerabilities,
+and data integrity risks that cause real production incidents.
+Return ONLY valid JSON — no markdown fences, no preamble."""
+
+
+_PROMPT_TMPL = """Audit the following database schema (and any embedded SQL) for ALL design issues, security vulnerabilities, and integrity risks.
+{pre_context}
+SCHEMA / SQL:
+---
+{schema}
+---
+
+Return a JSON object with EXACTLY these keys:
+{{
+  "health_score": <integer 0-100 — overall schema health; 100 = perfect, 0 = completely broken>,
+  "summary": "<1-2 sentence plain-language verdict — what's the biggest risk and overall state>",
+  "findings": [
+    {{
+      "severity": "<exactly one of: critical | warning | advice>",
+      "title": "<short issue title, max 6 words>",
+      "description": "<1-2 sentence explanation of the problem and why it matters in production>",
+      "location": "<exact table name, column name, procedure name, or SQL clause where the issue appears>",
+      "suggestion": "<concrete fix — include the actual corrected SQL snippet when applicable>"
+    }}
+  ]
+}}
+
+Severity definitions:
+- critical: causes data loss, security breach, or catastrophic data corruption. Examples:
+    * SQL injection via dynamic query string concatenation with user input
+    * DELETE or UPDATE statements with no WHERE clause (wipes entire table)
+    * Passwords or secrets stored in plaintext (no hashing)
+    * Missing PRIMARY KEY on a business entity table
+    * Circular or missing FOREIGN KEY constraints breaking referential integrity
+    * NULL allowed on columns that are business-critical (email, user_id, amount)
+- warning: degrades performance, risks integrity under load, or creates operational risk. Examples:
+    * Unindexed foreign key columns (causes full table scans on joins)
+    * TEXT type where VARCHAR(n) is appropriate (no length constraint)
+    * Missing NOT NULL on required business fields
+    * Missing updated_at / created_at audit columns
+    * Redundant or overlapping indexes (e.g. index on (a), (a,b), (a,b,c) — first is redundant)
+    * Missing transactions around multi-step operations
+- advice: maintainability and future-proofing. Examples:
+    * Vague column or table names (t1, col1, data, misc, info, temp — not what they represent)
+    * Single-letter or numeric table aliases in stored procedures
+    * Missing soft-delete pattern (no is_deleted / deleted_at column)
+    * No CHECK constraints on enum-like columns
+
+FK direction rule: the child table (many side) holds the FK column that references the parent (one side).
+  Correct: products.category_id REFERENCES categories(id) — products is the child, categories is the parent.
+  Wrong: reversed direction or FK defined on the parent side.
+
+Naming convention rule: the real problem is meaningless names (t1, t2, col1, data, misc).
+  NEVER suggest appending _table, _tbl, _record — that is an anti-pattern. Suggest descriptive real names instead.
+
+Rules:
+- Prioritize: list critical findings first, then warnings, then advice
+- The CONFIRMED CRITICAL ISSUES above MUST appear in findings as severity=critical — expand on each with real-world impact
+- Be specific: reference exact table/column names from the schema — do not generalise
+- suggestion must be actionable: if it is a SQL change, show the corrected SQL
+- health_score: start at 100, deduct 20-25 per critical, 5-10 per warning, 1-3 per advice; floor at 0
+- Minimum 3 findings if any issues exist; maximum 15
+- Do NOT fabricate issues that are not present in the schema"""
+
+
+def _pre_scan(sql: str) -> list[dict]:
+    """Deterministic regex scan for the most dangerous SQL patterns.
+    Returns findings that are guaranteed regardless of what the AI notices."""
+    findings = []
+
+    # 1. SQL Injection — dynamic exec of a variable built by string concatenation
+    # Covers: EXEC(@sql), EXECUTE(@sql), sp_executesql @sql
+    exec_pattern = re.compile(
+        r'(?i)(?:EXEC(?:UTE)?\s*\(\s*@\w+|sp_executesql\s+@\w+)', re.IGNORECASE
+    )
+    # Also catch: SET @var = '...' + @user_input (dynamic SQL building)
+    concat_pattern = re.compile(
+        r"(?i)SET\s+@\w+\s*=\s*(?:'[^']*'\s*\+|@\w+\s*\+)", re.IGNORECASE
+    )
+    lines = sql.splitlines()
+    injection_lines = []
+    for i, line in enumerate(lines, 1):
+        if exec_pattern.search(line) or concat_pattern.search(line):
+            injection_lines.append(f"line {i}: {line.strip()[:80]}")
+    if injection_lines:
+        findings.append({
+            "severity": "critical",
+            "title": "SQL Injection Vulnerability",
+            "description": (
+                "Dynamic SQL is constructed by concatenating user-supplied variables into a "
+                "query string and then executed with EXEC/EXECUTE. An attacker can inject "
+                "arbitrary SQL, bypassing all access controls and exfiltrating or destroying data."
+            ),
+            "location": "; ".join(injection_lines[:3]),
+            "suggestion": (
+                "Replace string concatenation with parameterized queries. "
+                "Use sp_executesql with typed parameters:\n"
+                "  EXEC sp_executesql N'SELECT * FROM users WHERE id = @id', "
+                "N'@id INT', @id = @user_input;"
+            ),
+        })
+
+    # 2. DELETE without WHERE — bare DELETE FROM <table> ;
+    for m in re.finditer(r'(?im)^\s*DELETE\s+FROM\s+(\w+)\s*;', sql):
+        table = m.group(1)
+        findings.append({
+            "severity": "critical",
+            "title": "DELETE Without WHERE Clause",
+            "description": (
+                f"DELETE FROM {table} has no WHERE clause — this permanently deletes "
+                f"every row in {table} on execution. One accidental or malicious call "
+                "destroys the entire table's data with no automatic rollback."
+            ),
+            "location": f"DELETE FROM {table}",
+            "suggestion": (
+                f"Always scope deletes: DELETE FROM {table} WHERE <condition>;\n"
+                f"If a full wipe is intentional, use TRUNCATE TABLE {table} explicitly "
+                "to make the intent obvious."
+            ),
+        })
+
+    # 3. UPDATE without WHERE — UPDATE <table> SET ... ; (no WHERE before semicolon)
+    for m in re.finditer(
+        r'(?is)UPDATE\s+(\w+)\s+SET\s+(?:(?!WHERE).)*?;', sql
+    ):
+        table = m.group(1)
+        stmt_preview = m.group(0).strip()[:80]
+        findings.append({
+            "severity": "critical",
+            "title": "UPDATE Without WHERE Clause",
+            "description": (
+                f"UPDATE {table} SET ... has no WHERE clause — this overwrites every "
+                f"row in {table}. Any typo or accidental execution corrupts the entire table."
+            ),
+            "location": stmt_preview,
+            "suggestion": (
+                f"Add a WHERE clause: UPDATE {table} SET ... WHERE <condition>;"
+            ),
+        })
+
+    # 4. Plaintext passwords in INSERT statements
+    # Look for INSERT ... (... password ...) VALUES (... 'literal' ...)
+    for m in re.finditer(
+        r"(?is)INSERT\s+INTO\s+\w+[^;]*?(?:password|passwd|pwd)[^;]*?VALUES[^;]*?'([^']{1,100})'[^;]*?;",
+        sql,
+    ):
+        findings.append({
+            "severity": "critical",
+            "title": "Plaintext Password Stored",
+            "description": (
+                "Passwords are inserted as plaintext string literals. Any database breach "
+                "or log exposure immediately reveals all user credentials with zero effort."
+            ),
+            "location": m.group(0).strip()[:80],
+            "suggestion": (
+                "Hash passwords before storage using bcrypt, argon2id, or scrypt. "
+                "Never store or log plaintext passwords:\n"
+                "  password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt())\n"
+                "  INSERT INTO users (password) VALUES (:password_hash)"
+            ),
+        })
+
+    return findings
+
+
+def analyze_schema(schema: str) -> dict:
+    """Audit a database schema and return structured findings."""
+    pre_findings = _pre_scan(schema)
+
+    # Inject pre-detected issues into the prompt so the AI elaborates on them
+    if pre_findings:
+        titles = "\n".join(f"  - {f['title']} (at: {f['location'][:60]})" for f in pre_findings)
+        pre_context = (
+            f"\n\nCONFIRMED CRITICAL ISSUES (detected by static analysis — "
+            f"you MUST include ALL of these in findings as severity=critical "
+            f"and explain their full real-world impact):\n{titles}\n"
+        )
+    else:
+        pre_context = ""
+
+    prompt = _PROMPT_TMPL.format(schema=schema[:8000], pre_context=pre_context)
+    result = call_ai_json(
+        [{"role": "user", "content": prompt}],
+        system=_SYSTEM,
+        max_tokens=3072,
+    )
+
+    if not result or not isinstance(result, dict):
+        # AI failed — return pre-findings only
+        return {
+            "health_score": max(0, 100 - 22 * len(pre_findings)),
+            "summary": "Static analysis detected critical security issues. AI elaboration unavailable.",
+            "findings": pre_findings,
+        }
+
+    if pre_findings:
+        # Deduplicate: remove any AI findings whose title overlaps with pre-detected ones
+        pre_titles = {f["title"].lower() for f in pre_findings}
+        ai_only = [
+            f for f in result.get("findings", [])
+            if f.get("title", "").lower() not in pre_titles
+        ]
+        # Pre-findings lead the list (guaranteed, most critical)
+        result["findings"] = pre_findings + ai_only
+        # Re-anchor health_score downward for guaranteed criticals
+        result["health_score"] = max(0, result.get("health_score", 100) - 22 * len(pre_findings))
+
+    return result
+
+
+_FIX_SYSTEM = (
+    "You are a senior database architect. Given a SQL schema with known issues, "
+    "produce a complete corrected version that fixes all listed problems. "
+    "Return ONLY valid SQL — no markdown fences, no preamble, no trailing commentary."
+)
+
+_FIX_PROMPT = """Fix the following SQL schema by addressing every listed issue.
+
+ORIGINAL SCHEMA:
+---
+{schema}
+---
+
+ISSUES TO FIX:
+{issues}
+
+Rules:
+- Return the COMPLETE corrected schema — all original tables must be present
+- Fix every issue listed: add missing PKs, hash passwords, add WHERE clauses, remove SQL injection, add indexes, etc.
+- Add brief inline comments only where a fix is non-obvious (e.g. -- hashed via bcrypt)
+- Do NOT add features that weren't in the original schema
+- Output valid SQL only"""
+
+
+def fix_schema(schema: str, findings: list) -> str:
+    """Return a corrected SQL schema that addresses all audit findings."""
+    issues = "\n".join(
+        f"- [{f.get('severity','').upper()}] {f.get('title','')}: {f.get('suggestion','')[:300]}"
+        for f in findings
+        if f.get("suggestion")
+    )
+    if not issues:
+        issues = "General cleanup — apply best practices for normalization, naming, and security."
+
+    prompt = _FIX_PROMPT.format(schema=schema[:6000], issues=issues)
+    return call_ai([{"role": "user", "content": prompt}], system=_FIX_SYSTEM, max_tokens=3000).strip()

app/tools/schema_detective/routes.py

@@ -0,0 +1,40 @@
+"""Schema Detective routes."""
+from flask import Blueprint, render_template, request, jsonify
+from .detective import analyze_schema, fix_schema
+
+bp = Blueprint("schema_detective", __name__, template_folder="templates")
+
+
+@bp.route("/")
+def index():
+    return render_template("schema_detective/index.html")
+
+
+@bp.route("/api/analyze", methods=["POST"])
+def api_analyze():
+    body = request.get_json(silent=True) or {}
+    schema = (body.get("schema") or "").strip()
+
+    if not schema:
+        return jsonify({"error": "Schema is required — paste your SQL or table definitions"}), 400
+    if len(schema) < 30:
+        return jsonify({"error": "Schema too short — paste at least one CREATE TABLE statement"}), 400
+
+    result = analyze_schema(schema)
+    if not result:
+        return jsonify({"error": "AI failed to analyze schema — please try again"}), 502
+    return jsonify(result)
+
+
+@bp.route("/api/fix", methods=["POST"])
+def api_fix():
+    body = request.get_json(silent=True) or {}
+    schema   = (body.get("schema") or "").strip()
+    findings = body.get("findings") or []
+    if not schema:
+        return jsonify({"error": "Schema is required"}), 400
+    try:
+        fixed = fix_schema(schema, findings)
+        return jsonify({"fixed_schema": fixed})
+    except Exception as e:
+        return jsonify({"error": f"Fix generation failed: {str(e)}"}), 502