feat: add liveboard blueprint planning

demoprep_app/liveboards/__init__.py

@@ -0,0 +1,2 @@
+"""Liveboard planning and TML enhancement helpers."""
+

demoprep_app/liveboards/blueprint.py

@@ -0,0 +1,313 @@
+"""Liveboard blueprint helpers for filters and demo-runner notes.
+
+The blueprint layer is intentionally conservative. It adds a small number of
+business-facing filters and a demo guide tile after MCP has created answers,
+without trying to replace the answer-generation flow.
+"""
+
+from __future__ import annotations
+
+import re
+from copy import deepcopy
+from typing import Any, Dict, Iterable, List, Tuple
+
+
+DEFAULT_APP_NAME = "DemoPrep"
+DEMO_GUIDE_VIZ_ID = "Viz_99"
+
+
+def build_liveboard_blueprint(
+    company_data: Dict[str, Any],
+    use_case: str,
+    model_columns: List[Dict[str, Any]] | None = None,
+    target_filter_count: int = 3,
+) -> Dict[str, Any]:
+    """Build a small liveboard blueprint from model metadata and story context."""
+    model_columns = model_columns or []
+    filters = choose_global_filters(model_columns, target_filter_count=target_filter_count)
+    return {
+        "company_name": company_data.get("name", "Company"),
+        "use_case": use_case or company_data.get("use_case", "Analytics"),
+        "app_name": company_data.get("app_name", DEFAULT_APP_NAME),
+        "filters": filters,
+        "demo_notes_tile": build_demo_notes_spec(company_data, use_case, filters),
+        "validation_rules": {
+            "filter_count_min": 2,
+            "filter_count_max": 6,
+            "filters_start_unfiltered": True,
+            "avoid_technical_filter_fields": True,
+            "demo_notes_tile_required": True,
+        },
+    }
+
+
+def choose_global_filters(
+    model_columns: List[Dict[str, Any]],
+    target_filter_count: int = 3,
+    min_filter_count: int = 2,
+    max_filter_count: int = 6,
+) -> List[Dict[str, Any]]:
+    """Choose business-friendly, unfiltered global filter chips from columns."""
+    target = max(min_filter_count, min(int(target_filter_count or 3), max_filter_count))
+    candidates: List[Tuple[int, int, Dict[str, Any]]] = []
+
+    for index, column in enumerate(model_columns or []):
+        raw_name = str(column.get("name") or "").strip()
+        if not raw_name or _is_bad_filter_column(raw_name, column):
+            continue
+        display_name = _filter_display_name(raw_name)
+        if not display_name or _is_bad_display_name(display_name):
+            continue
+        score = _filter_score(raw_name, display_name, column)
+        if score <= 0:
+            continue
+        candidates.append((score, -index, {"column": [raw_name], "is_mandatory": False, "is_single_value": False, "display_name": display_name}))
+
+    selected: List[Dict[str, Any]] = []
+    seen_display: set[str] = set()
+    seen_concepts: set[str] = set()
+
+    for _score, _negative_index, filter_spec in sorted(candidates, reverse=True):
+        display = str(filter_spec["display_name"])
+        concept = _filter_concept(display)
+        if display.lower() in seen_display or concept in seen_concepts:
+            continue
+        selected.append(filter_spec)
+        seen_display.add(display.lower())
+        seen_concepts.add(concept)
+        if len(selected) >= target:
+            break
+
+    return selected
+
+
+def apply_blueprint_to_liveboard_tml(
+    liveboard_tml: Dict[str, Any],
+    blueprint: Dict[str, Any],
+) -> Tuple[Dict[str, Any], List[str]]:
+    """Apply global filters and a demo guide tile to a liveboard TML dict."""
+    updated = deepcopy(liveboard_tml)
+    liveboard = updated.setdefault("liveboard", {})
+    changes: List[str] = []
+
+    filters = blueprint.get("filters") or []
+    if filters:
+        liveboard["filters"] = _merge_filters(liveboard.get("filters", []), filters)
+        changes.append(f"Added {len(filters)} global filter(s)")
+
+    demo_notes = blueprint.get("demo_notes_tile") or {}
+    if demo_notes:
+        _upsert_demo_guide_tile(liveboard, demo_notes)
+        changes.append("Added demo guide tile")
+
+    return updated, changes
+
+
+def build_demo_notes_spec(
+    company_data: Dict[str, Any],
+    use_case: str,
+    filters: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """Return content for the demo guide tile."""
+    persona = (
+        company_data.get("target_persona")
+        or company_data.get("persona")
+        or "Business leader"
+    )
+    business_problem = (
+        company_data.get("business_problem")
+        or company_data.get("research")
+        or company_data.get("additional_context")
+        or "Use the liveboard to identify changes, drivers, and follow-up actions."
+    )
+    business_problem = _compact_sentence(str(business_problem), max_chars=220)
+    use_case_display = use_case or company_data.get("use_case", "Analytics")
+    filter_names = [str(f.get("display_name")) for f in filters if f.get("display_name")]
+
+    return {
+        "id": DEMO_GUIDE_VIZ_ID,
+        "title": "Demo Guide",
+        "placement": "bottom",
+        "html": _demo_notes_html(
+            company_name=company_data.get("name", "Company"),
+            use_case=use_case_display,
+            app_name=company_data.get("app_name", DEFAULT_APP_NAME),
+            persona=persona,
+            business_problem=business_problem,
+            filters=filter_names,
+        ),
+    }
+
+
+def _demo_notes_html(
+    company_name: str,
+    use_case: str,
+    app_name: str,
+    persona: str,
+    business_problem: str,
+    filters: List[str],
+) -> str:
+    filters_text = ", ".join(filters) if filters else "Use dashboard filters only when the story needs narrowing."
+    spotter_one = f"Where should {company_name} focus first for {use_case.lower()}?"
+    spotter_two = "Which segment, location, or category is driving the biggest change?"
+    return f"""<div style="background:#101820; color:#ffffff; border-radius:12px; padding:18px 20px; font-family:Inter, Arial, sans-serif;">
+<div style="font-size:12px; letter-spacing:1.8px; text-transform:uppercase; color:#40c1c0; font-weight:700; margin-bottom:8px;">Demo Guide</div>
+<h3 class="theme-module__editor-h3" style="margin:0 0 10px 0;"><span style="color:#ffffff; white-space:pre-wrap;">{_escape(company_name)}: {_escape(use_case)}</span></h3>
+<p class="theme-module__editor-paragraph" style="margin:0 0 10px 0;"><b><strong style="color:#ffffff;">Audience:</strong></b><span style="color:#d6dde8; white-space:pre-wrap;"> {_escape(str(persona))}</span></p>
+<p class="theme-module__editor-paragraph" style="margin:0 0 10px 0;"><b><strong style="color:#ffffff;">Demo path:</strong></b><span style="color:#d6dde8; white-space:pre-wrap;"> Start with the executive KPIs, explain the primary trend, then use the breakdowns to identify where action is needed.</span></p>
+<p class="theme-module__editor-paragraph" style="margin:0 0 10px 0;"><b><strong style="color:#ffffff;">Filters to try:</strong></b><span style="color:#d6dde8; white-space:pre-wrap;"> {_escape(filters_text)}</span></p>
+<p class="theme-module__editor-paragraph" style="margin:0 0 10px 0;"><b><strong style="color:#ffffff;">Story prompt:</strong></b><span style="color:#d6dde8; white-space:pre-wrap;"> {_escape(business_problem)}</span></p>
+<ul style="margin:8px 0 0 20px; padding:0; color:#d6dde8;">
+<li>{_escape(spotter_one)}</li>
+<li>{_escape(spotter_two)}</li>
+</ul>
+<div style="margin-top:14px; font-size:12px; color:#40c1c0;">Built with {_escape(app_name)}</div>
+</div>"""
+
+
+def _merge_filters(existing_filters: List[Dict[str, Any]], new_filters: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    merged = list(existing_filters or [])
+    seen = {tuple(f.get("column", [])) for f in merged if isinstance(f, dict)}
+    for filter_spec in new_filters:
+        key = tuple(filter_spec.get("column", []))
+        if key in seen:
+            continue
+        merged.append(filter_spec)
+        seen.add(key)
+    return merged
+
+
+def _upsert_demo_guide_tile(liveboard: Dict[str, Any], demo_notes: Dict[str, Any]) -> None:
+    visualizations = liveboard.setdefault("visualizations", [])
+    demo_id = _resolve_demo_guide_id(visualizations, str(demo_notes.get("id") or DEMO_GUIDE_VIZ_ID))
+    html = demo_notes.get("html", "")
+    existing = next((viz for viz in visualizations if viz.get("id") == demo_id), None)
+    if existing:
+        existing["note_tile"] = {"html_parsed_string": html}
+    else:
+        visualizations.append({"id": demo_id, "note_tile": {"html_parsed_string": html}})
+
+    _place_demo_tile_at_bottom(liveboard, str(demo_id))
+
+
+def _resolve_demo_guide_id(visualizations: List[Dict[str, Any]], requested_id: str) -> str:
+    for viz in visualizations:
+        if viz.get("id") == requested_id:
+            return requested_id
+    for viz in visualizations:
+        note_tile = viz.get("note_tile")
+        html = ""
+        if isinstance(note_tile, dict):
+            html = str(note_tile.get("html_parsed_string") or "")
+        elif note_tile:
+            html = str(note_tile)
+        if "Demo Guide" in html and "Built with DemoPrep" in html:
+            return str(viz.get("id"))
+    used_ids = {str(viz.get("id")) for viz in visualizations}
+    if requested_id.startswith("Viz_") and requested_id not in used_ids and requested_id[4:].isdigit():
+        return requested_id
+    numeric_ids = []
+    for viz_id in used_ids:
+        match = re.fullmatch(r"Viz_(\d+)", viz_id)
+        if match:
+            numeric_ids.append(int(match.group(1)))
+    next_id = max(numeric_ids or [0]) + 1
+    while f"Viz_{next_id}" in used_ids:
+        next_id += 1
+    return f"Viz_{next_id}"
+
+
+def _place_demo_tile_at_bottom(liveboard: Dict[str, Any], demo_id: str) -> None:
+    tabs = liveboard.setdefault("layout", {}).setdefault("tabs", [])
+    if not tabs:
+        tabs.append({"name": "Executive Overview", "tiles": []})
+    target_tab = tabs[-1]
+    tiles = target_tab.setdefault("tiles", [])
+    tiles[:] = [tile for tile in tiles if tile.get("visualization_id") != demo_id]
+    y = _next_tile_y(tiles)
+    tiles.append({"visualization_id": demo_id, "x": 0, "y": y, "height": 7, "width": 12})
+
+
+def _next_tile_y(tiles: Iterable[Dict[str, Any]]) -> int:
+    max_y = 0
+    for tile in tiles:
+        try:
+            max_y = max(max_y, int(tile.get("y", 0)) + int(tile.get("height", 0)))
+        except (TypeError, ValueError):
+            continue
+    return max_y
+
+
+def _filter_score(raw_name: str, display_name: str, column: Dict[str, Any]) -> int:
+    low = raw_name.lower()
+    display_low = display_name.lower()
+    score = 0
+    if any(token in low for token in ("program", "campus", "segment", "category", "scenario", "region", "state", "channel", "term")):
+        score += 50
+    if any(token in low for token in ("product", "customer", "store", "supplier", "provider", "department", "market")):
+        score += 35
+    if "name" in low:
+        score += 10
+    if display_low in {"program", "campus", "student segment", "scenario", "term", "region", "category", "channel"}:
+        score += 20
+    if any(token in low for token in ("date", "month start", "full date")):
+        score += 15
+    return score
+
+
+def _is_bad_filter_column(raw_name: str, column: Dict[str, Any]) -> bool:
+    low = raw_name.lower()
+    column_type = str(column.get("type") or column.get("column_type") or "").upper()
+    if any(token in low for token in (" key", "_key", " id", "_id", "guid", "uuid", "number")):
+        return True
+    if any(token in low for token in ("pct", "rate", "amount", "revenue", "sales", "units", "count", "volume", "value", "students", "applications", "admissions", "enrollments")):
+        return True
+    if column_type in {"MEASURE", "NUMBER", "INT", "INTEGER", "DOUBLE", "FLOAT", "DECIMAL"}:
+        return True
+    return False
+
+
+def _is_bad_display_name(display_name: str) -> bool:
+    low = display_name.lower()
+    return low in {"name", "date key", "month key"} or len(display_name) > 32
+
+
+def _filter_display_name(raw_name: str) -> str:
+    name = re.sub(r"^(Prog|Camp|Stud|Term|Enro|Regi|Prod|Supp|Ware)\s+", "", raw_name).strip()
+    name = re.sub(r"\s+Name$", "", name).strip()
+    name = re.sub(r"\s+Category$", " Category", name).strip()
+    replacements = {
+        "Student Segment": "Student Segment",
+        "Scenario Category": "Scenario",
+        "Month Start Date": "Month",
+        "Full Date": "Date",
+        "Program": "Program",
+        "Campus": "Campus",
+        "Term": "Term",
+    }
+    return replacements.get(name, name)
+
+
+def _filter_concept(display_name: str) -> str:
+    low = display_name.lower()
+    for concept in ("program", "campus", "student segment", "segment", "scenario", "term", "region", "category", "channel", "date", "month"):
+        if concept in low:
+            return concept
+    return low
+
+
+def _compact_sentence(value: str, max_chars: int = 220) -> str:
+    text = " ".join(value.split())
+    if len(text) <= max_chars:
+        return text
+    return text[: max_chars - 1].rsplit(" ", 1)[0] + "."
+
+
+def _escape(value: str) -> str:
+    return (
+        str(value)
+        .replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )

demoprep_app/liveboards/golden_layout.py

@@ -0,0 +1,695 @@
+"""Golden-demo-inspired liveboard planning and TML layout helpers.
+
+These helpers are intentionally pure: they operate on TML dictionaries and do
+not call ThoughtSpot. That keeps the liveboard lab fast to test while the
+existing MCP-first creation path remains the source of liveboard content.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Dict, Iterable, List, Tuple
+
+
+EXECUTIVE_TAB = "Executive Overview"
+OPERATIONS_TAB = "Manager Drilldown"
+
+
+def build_dashboard_plan(
+    company_name: str,
+    use_case: str,
+    target_viz_count: int = 16,
+) -> Dict[str, Any]:
+    """Return the first-pass dashboard architecture for lab-created liveboards."""
+    target_viz_count = max(8, min(int(target_viz_count or 16), 24))
+    kpi_count = 4 if target_viz_count >= 14 else 3
+    executive_tab, manager_tab = _tab_names_for_use_case(use_case)
+    return {
+        "company_name": company_name,
+        "use_case": use_case,
+        "executive_tab": executive_tab,
+        "manager_tab": manager_tab,
+        "target_viz_count": target_viz_count,
+        "audiences": [
+            {
+                "name": "Executive",
+                "tab": executive_tab,
+                "intent": "CEO/CRO/CFO-level summary of performance, changes, and risks.",
+            },
+            {
+                "name": "Manager",
+                "tab": manager_tab,
+                "intent": "Operator-level breakdowns for action, ownership, and follow-up.",
+            },
+        ],
+        "sections": [
+            {
+                "name": "Key Performance Metrics",
+                "tab": executive_tab,
+                "role": "kpi",
+                "target_count": kpi_count,
+            },
+            {
+                "name": "Performance Trends",
+                "tab": executive_tab,
+                "role": "trend",
+                "target_count": 2,
+            },
+            {
+                "name": "Performance Drivers",
+                "tab": executive_tab,
+                "role": "driver",
+                "target_count": 2,
+            },
+            {
+                "name": _manager_breakdown_name(use_case),
+                "tab": manager_tab,
+                "role": "breakdown",
+                "target_count": 4,
+            },
+            {
+                "name": "Top Opportunities",
+                "tab": manager_tab,
+                "role": "ranking",
+                "target_count": 3,
+            },
+            {
+                "name": "Detail Review",
+                "tab": manager_tab,
+                "role": "detail",
+                "target_count": 2,
+            },
+        ],
+        "style": {
+            "border": "CURVED",
+            "brand_color": "LBC_A",
+            "group_colors": ["GBC_C", "GBC_A", "GBC_C", "GBC_A", "GBC_C", "GBC_A"],
+            "highlight_kpis": True,
+        },
+    }
+
+
+def summarize_liveboard_tml(liveboard_tml: Dict[str, Any]) -> Dict[str, Any]:
+    """Produce a compact, test-friendly summary of liveboard structure."""
+    liveboard = liveboard_tml.get("liveboard", {})
+    visualizations = liveboard.get("visualizations", [])
+    groups = liveboard.get("groups", [])
+    tabs = liveboard.get("layout", {}).get("tabs", [])
+    chart_types: Dict[str, int] = {}
+    for viz in visualizations:
+        chart_type = _chart_type(viz)
+        chart_types[chart_type] = chart_types.get(chart_type, 0) + 1
+    return {
+        "name": liveboard.get("name", ""),
+        "visualization_count": len(visualizations),
+        "group_count": len(groups),
+        "tab_names": [tab.get("name", "") for tab in tabs],
+        "chart_types": chart_types,
+        "group_names": [group.get("name", "") for group in groups],
+    }
+
+
+def apply_golden_two_tab_layout(
+    liveboard_tml: Dict[str, Any],
+    plan: Dict[str, Any] | None = None,
+) -> Tuple[Dict[str, Any], List[str]]:
+    """Return a copy of TML with two tabs, thematic groups, and golden styling."""
+    updated = deepcopy(liveboard_tml)
+    liveboard = updated.setdefault("liveboard", {})
+    plan = plan or build_dashboard_plan(liveboard.get("name", "Company"), "Analytics")
+
+    visualizations = list(liveboard.get("visualizations", []))
+    note_viz = next((viz for viz in visualizations if "note_tile" in viz), None)
+    data_visualizations = [viz for viz in visualizations if "note_tile" not in viz]
+    liveboard["visualizations"] = visualizations
+
+    kpi_changes = _convert_periodic_metric_charts(data_visualizations)
+    chart_changes = _reduce_heatmaps_and_apply_palettes(data_visualizations)
+    groups = _build_groups(data_visualizations, plan)
+    if note_viz:
+        _apply_overview_note(note_viz, plan, groups)
+    liveboard["groups"] = groups
+    note_viz_id = note_viz.get("id") if note_viz else None
+    liveboard["layout"] = {"tabs": _build_tabs(groups, note_viz_id=note_viz_id, plan=plan)}
+    _apply_style(liveboard, groups, plan, note_viz_id=note_viz_id)
+
+    changes = [
+        f"Applied golden two-tab layout ({len(groups)} groups)",
+        f"Tabs: {_executive_tab_name(plan)}, {_manager_tab_name(plan)}",
+    ]
+    for change in (kpi_changes, chart_changes):
+        if change:
+            changes.append(change)
+    return updated, changes
+
+
+def _build_groups(visualizations: List[Dict[str, Any]], plan: Dict[str, Any]) -> List[Dict[str, Any]]:
+    buckets = {
+        "kpi": [],
+        "trend": [],
+        "driver": [],
+        "breakdown": [],
+        "ranking": [],
+        "detail": [],
+    }
+
+    for viz in visualizations:
+        buckets[_role_for_viz(viz)].append(viz.get("id", ""))
+
+    # Keep non-empty ids only, preserving exported viz order.
+    for role, ids in buckets.items():
+        buckets[role] = [viz_id for viz_id in ids if viz_id]
+
+    overflow = []
+    assigned = set()
+    for role in ("kpi", "trend", "driver", "breakdown", "ranking", "detail"):
+        assigned.update(buckets[role])
+    for viz in visualizations:
+        viz_id = viz.get("id", "")
+        if viz_id and viz_id not in assigned:
+            overflow.append(viz_id)
+    buckets["breakdown"].extend(overflow)
+
+    groups = []
+    for section in plan.get("sections", []):
+        role = section.get("role", "")
+        ids = buckets.get(role, [])
+        if not ids:
+            continue
+        target_count = max(1, int(section.get("target_count") or 4))
+        for chunk_index, chunk in enumerate(_chunks(ids, target_count)):
+            section_name = section.get("name", role.title())
+            groups.append(
+                {
+                    "id": f"Group_{len(groups) + 1}",
+                    "name": _chunked_group_name(section_name, chunk_index),
+                    "description": _section_description(section_name, section.get("tab", "")),
+                    "tab": section.get("tab", ""),
+                    "visualizations": chunk,
+                }
+            )
+    return groups
+
+
+def _build_tabs(
+    groups: List[Dict[str, Any]],
+    note_viz_id: str | None = None,
+    plan: Dict[str, Any] | None = None,
+) -> List[Dict[str, Any]]:
+    plan = plan or {}
+    executive_tab = _executive_tab_name(plan)
+    manager_tab = _manager_tab_name(plan)
+    executive_groups = [group for group in groups if group.get("tab") == executive_tab]
+    operations_groups = [group for group in groups if group.get("tab") == manager_tab]
+
+    if not executive_groups:
+        executive_groups = groups[:1]
+        operations_groups = groups[1:]
+
+    tabs = []
+    tabs.append(
+        {
+            "name": executive_tab,
+            "description": "Executive-ready performance summary and key drivers",
+            "tiles": _top_level_tiles(executive_groups, note_viz_id=note_viz_id),
+            "group_layouts": [_group_layout(group) for group in executive_groups],
+        }
+    )
+
+    if operations_groups:
+        tabs.append(
+            {
+                "name": manager_tab,
+                "description": "Manager-level breakdowns, rankings, and detail",
+                "tiles": _top_level_tiles(operations_groups),
+                "group_layouts": [_group_layout(group) for group in operations_groups],
+            }
+        )
+    return tabs
+
+
+def _top_level_tiles(
+    groups: List[Dict[str, Any]],
+    note_viz_id: str | None = None,
+) -> List[Dict[str, int | str]]:
+    tiles: List[Dict[str, int | str]] = []
+    y = 0
+    for index, group in enumerate(groups):
+        viz_count = len(group.get("visualizations", []))
+        is_kpi = index == 0 and "Metric" in group.get("name", "")
+        if is_kpi:
+            height = 7
+            width = 9 if note_viz_id else 12
+            x = 3 if note_viz_id else 0
+            if note_viz_id:
+                tiles.append(
+                    {
+                        "visualization_id": note_viz_id,
+                        "x": 0,
+                        "y": 0,
+                        "height": 7,
+                        "width": 3,
+                    }
+                )
+        else:
+            height = _group_tile_height(viz_count)
+            width = 6 if len(groups) > 2 and index > 0 else 12
+            x = 0 if index % 2 else 6
+            if width == 12:
+                x = 0
+        if index == 1:
+            y = 7
+        elif index > 1 and index % 2 == 1:
+            y += max(8, height)
+        tiles.append(
+            {
+                "visualization_id": group.get("id", ""),
+                "x": x,
+                "y": y,
+                "height": height,
+                "width": width,
+            }
+        )
+        if width == 12:
+            y += height
+    return tiles
+
+
+def _group_layout(group: Dict[str, Any]) -> Dict[str, Any]:
+    viz_ids = group.get("visualizations", [])
+    is_kpi = "Metric" in group.get("name", "")
+    tiles = []
+    for index, viz_id in enumerate(viz_ids):
+        if is_kpi:
+            if len(viz_ids) <= 2:
+                width = 6
+            elif len(viz_ids) == 3:
+                width = 4
+            else:
+                width = 3
+            columns = max(1, 12 // width)
+            tiles.append(
+                {
+                    "visualization_id": viz_id,
+                    "x": (index % columns) * width,
+                    "y": (index // columns) * 7,
+                    "height": 7,
+                    "width": width,
+                }
+            )
+        else:
+            tiles.append(
+                {
+                    "visualization_id": viz_id,
+                    "x": 0 if index % 2 == 0 else 6,
+                    "y": (index // 2) * 8,
+                    "height": 8,
+                    "width": 6,
+                }
+            )
+    return {"id": group.get("id", ""), "tiles": tiles}
+
+
+def _group_tile_height(viz_count: int) -> int:
+    if viz_count <= 1:
+        return 8
+    rows = (viz_count + 1) // 2
+    return max(8, rows * 8)
+
+
+def _apply_style(
+    liveboard: Dict[str, Any],
+    groups: List[Dict[str, Any]],
+    plan: Dict[str, Any],
+    note_viz_id: str | None = None,
+) -> None:
+    style_config = plan.get("style", {})
+    style = liveboard.setdefault("style", {})
+    style["style_properties"] = _merge_style_properties(
+        style.get("style_properties", []),
+        {
+            "lb_border_type": style_config.get("border", "CURVED"),
+            "lb_brand_color": style_config.get("brand_color", "LBC_A"),
+            "hide_group_title": "false",
+            "hide_group_description": "false",
+            "hide_group_tile_description": "false",
+            "hide_tile_description": "false",
+            "kpi_hero_font_size": "M",
+        },
+    )
+
+    overrides = list(style.get("overrides", []))
+    current_group_ids = {group.get("id") for group in groups if group.get("id")}
+    overrides = [
+        override for override in overrides
+        if not str(override.get("object_id", "")).startswith("Group_")
+        or override.get("object_id") in current_group_ids
+    ]
+    if note_viz_id:
+        overrides = [
+            override for override in overrides
+            if override.get("object_id") != note_viz_id
+        ]
+    group_colors = style_config.get("group_colors", ["GBC_C", "GBC_A"])
+    for index, group in enumerate(groups):
+        overrides = _upsert_override(
+            overrides,
+            group.get("id", ""),
+            {"group_brand_color": group_colors[index % len(group_colors)]},
+        )
+        if index == 0 and style_config.get("highlight_kpis", True):
+            for viz_id in group.get("visualizations", []):
+                overrides = _upsert_override(overrides, viz_id, {"is_highlighted": "true"})
+    style["overrides"] = overrides
+
+
+def _apply_overview_note(
+    note_viz: Dict[str, Any],
+    plan: Dict[str, Any],
+    groups: List[Dict[str, Any]],
+) -> None:
+    company_name = plan.get("company_name") or "Company"
+    use_case = plan.get("use_case") or "Analytics"
+    initials = "".join(part[0] for part in company_name.replace("-", " ").split()[:2]).upper()
+    bullets = [
+        "Executive KPIs with trend context",
+        f"{len(groups)} guided analysis sections",
+        "Operational drivers for manager follow-up",
+    ]
+    html = f"""<h1 class="theme-module__editor-h1"><span style="color: rgb(46, 117, 240); white-space: pre-wrap;">{initials}</span></h1>
+<p class="theme-module__editor-paragraph"><br></p>
+<h2 class="theme-module__editor-h2"><span style="color: rgb(240, 65, 82); white-space: pre-wrap;">INSIGHT OVERVIEW</span></h2>
+<p class="theme-module__editor-paragraph"><span style="white-space: pre-wrap;">{company_name} {use_case} review for executive and manager audiences.</span></p>
+<ul class="theme-module__editor-ul">
+<li class="theme-module__editor-list-item"><span style="white-space: pre-wrap;">{bullets[0]}</span></li>
+<li class="theme-module__editor-list-item"><span style="white-space: pre-wrap;">{bullets[1]}</span></li>
+<li class="theme-module__editor-list-item"><span style="white-space: pre-wrap;">{bullets[2]}</span></li>
+</ul>"""
+    note_tile = note_viz.setdefault("note_tile", {})
+    if isinstance(note_tile, dict):
+        note_tile["html_parsed_string"] = html
+    else:
+        note_viz["note_tile"] = {"html_parsed_string": html}
+
+
+def _reduce_heatmaps_and_apply_palettes(visualizations: List[Dict[str, Any]]) -> str:
+    """Keep heatmaps rare and add varied chart colors to avoid all-blue boards."""
+    heatmaps_seen = 0
+    heatmaps_converted = 0
+    palettes_applied = 0
+
+    for index, viz in enumerate(visualizations):
+        answer = viz.get("answer", {})
+        chart = answer.get("chart", {})
+        chart_type = _chart_type(viz)
+
+        if chart_type == "HEATMAP":
+            heatmaps_seen += 1
+            if heatmaps_seen > 2:
+                chart["type"] = _replacement_chart_type(answer)
+                chart_type = chart["type"]
+                heatmaps_converted += 1
+
+        if chart_type not in {"KPI", "NOTE", "UNKNOWN"}:
+            _apply_chart_palette(chart, index)
+            palettes_applied += 1
+
+    parts = []
+    if heatmaps_converted:
+        parts.append(f"Converted {heatmaps_converted} extra heatmap(s)")
+    if palettes_applied:
+        parts.append(f"Applied varied palettes to {palettes_applied} chart(s)")
+    return "; ".join(parts)
+
+
+def _convert_periodic_metric_charts(visualizations: List[Dict[str, Any]]) -> str:
+    """Turn simple time-series metric answers into real ThoughtSpot KPI charts."""
+    converted = 0
+    for viz in visualizations:
+        if _role_for_viz(viz) != "kpi" or _chart_type(viz) == "KPI":
+            continue
+
+        answer = viz.get("answer", {})
+        chart = answer.get("chart", {})
+        date_column, measure_column = _kpi_axis_columns(answer)
+        if not date_column or not measure_column:
+            continue
+
+        answer["display_mode"] = "CHART_MODE"
+        chart["type"] = "KPI"
+        chart["axis_configs"] = [{"x": [date_column], "y": [measure_column]}]
+        chart["chart_columns"] = [
+            {"column_id": date_column},
+            {"column_id": measure_column},
+        ]
+        chart.pop("client_state_v2", None)
+        converted += 1
+
+    if converted:
+        return f"Converted {converted} periodic metric chart(s) to KPI"
+    return ""
+
+
+def _kpi_axis_columns(answer: Dict[str, Any]) -> Tuple[str | None, str | None]:
+    columns = _answer_column_names(answer)
+    if len(columns) < 2:
+        columns = _chart_column_names(answer.get("chart", {}))
+
+    date_column = next((column for column in columns if _looks_like_date_column(column)), None)
+    measure_column = next((column for column in columns if column != date_column), None)
+    return date_column, measure_column
+
+
+def _answer_column_names(answer: Dict[str, Any]) -> List[str]:
+    names = []
+    for column in answer.get("answer_columns", []) or []:
+        name = _column_name(column)
+        if name:
+            names.append(name)
+    return names
+
+
+def _chart_column_names(chart: Dict[str, Any]) -> List[str]:
+    names = []
+    for column in chart.get("chart_columns", []) or []:
+        name = _column_name(column)
+        if name:
+            names.append(name)
+    return names
+
+
+def _column_name(column: Any) -> str | None:
+    if isinstance(column, str):
+        return column
+    if isinstance(column, dict):
+        for key in ("column_id", "name", "id"):
+            value = column.get(key)
+            if value:
+                return str(value)
+    return None
+
+
+def _looks_like_date_column(column: str) -> bool:
+    lowered = column.lower()
+    return any(
+        token in lowered
+        for token in (
+            "date",
+            "week(",
+            "month(",
+            "quarter(",
+            "year(",
+            "day(",
+            "week start",
+            "month start",
+        )
+    )
+
+
+def _replacement_chart_type(answer: Dict[str, Any]) -> str:
+    name = answer.get("name", "").lower()
+    query = answer.get("search_query", "").lower()
+    text = f"{name} {query}"
+    if any(word in text for word in ("rate", "ratio", "retention", "win rate", "attainment")):
+        return "ADVANCED_COLUMN"
+    if any(word in text for word in ("top ", "client", "account", "rep", "engagement")):
+        return "ADVANCED_BAR"
+    return "ADVANCED_COLUMN"
+
+
+def _apply_chart_palette(chart: Dict[str, Any], index: int) -> None:
+    palettes = [
+        ["#06BF7F", "#48D1E0", "#2E75F0"],
+        ["#8C62F5", "#D66EFA", "#F45BA8"],
+        ["#FF8142", "#FCC838", "#F7A11A"],
+        ["#40C1C0", "#2458C9", "#6AA6FF"],
+        ["#F45BA8", "#8C62F5", "#D66EFA"],
+        ["#7B61FF", "#00A3A3", "#FFB84D"],
+        ["#2359B6", "#06BF7F", "#FCC838"],
+        ["#B06C00", "#FF8142", "#F7A11A"],
+    ]
+    palette = palettes[index % len(palettes)]
+    client_state = _load_chart_client_state(chart)
+    chart_properties = client_state.setdefault("chartProperties", {})
+    chart_properties["chartLevelColorConfig"] = {
+        "colorPalette": {"colors": palette}
+    }
+    series_colors = _series_colors_for_chart(chart, palette)
+    if series_colors:
+        client_state["seriesColors"] = series_colors
+        client_state["systemSeriesColors"] = series_colors
+    chart["client_state_v2"] = json_dumps_compact(client_state)
+
+
+def _series_colors_for_chart(chart: Dict[str, Any], palette: List[str]) -> List[Dict[str, str]]:
+    measure_columns = [
+        column
+        for column in _chart_column_names(chart)
+        if not _looks_like_date_column(column) and column.lower() not in {"measure names", "measure values"}
+    ]
+    if not measure_columns:
+        return []
+    return [
+        {"serieName": column, "color": palette[index % len(palette)]}
+        for index, column in enumerate(measure_columns)
+    ]
+
+
+def _load_chart_client_state(chart: Dict[str, Any]) -> Dict[str, Any]:
+    raw = chart.get("client_state_v2")
+    if not raw:
+        return {"version": "V4DOT2"}
+    try:
+        import json
+
+        value = json.loads(raw)
+        if isinstance(value, dict):
+            return value
+    except Exception:
+        pass
+    return {"version": "V4DOT2"}
+
+
+def json_dumps_compact(value: Dict[str, Any]) -> str:
+    import json
+
+    return json.dumps(value, separators=(",", ":"))
+
+
+def _tab_names_for_use_case(use_case: str) -> Tuple[str, str]:
+    text = (use_case or "").lower()
+    if any(token in text for token in ("professional service", "consulting", "advisory")):
+        return EXECUTIVE_TAB, "Practice Management"
+    if any(token in text for token in ("sales", "saas", "pipeline", "arr")):
+        return EXECUTIVE_TAB, "Sales Management"
+    if any(token in text for token in ("trucking", "transport", "fleet", "logistics")):
+        return EXECUTIVE_TAB, "Fleet Management"
+    if any(token in text for token in ("finance", "financial", "margin")):
+        return EXECUTIVE_TAB, "Finance Detail"
+    return EXECUTIVE_TAB, OPERATIONS_TAB
+
+
+def _manager_breakdown_name(use_case: str) -> str:
+    text = (use_case or "").lower()
+    if any(token in text for token in ("professional service", "consulting", "advisory")):
+        return "Practice Breakdowns"
+    if any(token in text for token in ("sales", "saas", "pipeline", "arr")):
+        return "Sales Breakdowns"
+    if any(token in text for token in ("trucking", "transport", "fleet", "logistics")):
+        return "Fleet Breakdowns"
+    if any(token in text for token in ("finance", "financial", "margin")):
+        return "Financial Breakdowns"
+    return "Manager Breakdowns"
+
+
+def _executive_tab_name(plan: Dict[str, Any]) -> str:
+    return plan.get("executive_tab") or EXECUTIVE_TAB
+
+
+def _manager_tab_name(plan: Dict[str, Any]) -> str:
+    return plan.get("manager_tab") or OPERATIONS_TAB
+
+
+def _merge_style_properties(
+    existing: Iterable[Dict[str, str]],
+    updates: Dict[str, str],
+) -> List[Dict[str, str]]:
+    by_name = {item.get("name"): dict(item) for item in existing if item.get("name")}
+    for name, value in updates.items():
+        by_name[name] = {"name": name, "value": value}
+    return list(by_name.values())
+
+
+def _upsert_override(
+    overrides: List[Dict[str, Any]],
+    object_id: str,
+    updates: Dict[str, str],
+) -> List[Dict[str, Any]]:
+    if not object_id:
+        return overrides
+    for override in overrides:
+        if override.get("object_id") == object_id:
+            override["style_properties"] = _merge_style_properties(
+                override.get("style_properties", []),
+                updates,
+            )
+            return overrides
+    overrides.append(
+        {
+            "object_id": object_id,
+            "style_properties": [{"name": name, "value": value} for name, value in updates.items()],
+        }
+    )
+    return overrides
+
+
+def _role_for_viz(viz: Dict[str, Any]) -> str:
+    chart_type = _chart_type(viz)
+    name = viz.get("answer", {}).get("name", "").lower()
+    query = viz.get("answer", {}).get("search_query", "").lower()
+    text = f"{name} {query}"
+
+    if chart_type == "KPI":
+        return "kpi"
+    if "TABLE" in chart_type:
+        return "detail"
+    if (
+        chart_type in {"LINE", "AREA", "ADVANCED_LINE", "ADVANCED_AREA"}
+        and any(period in text for period in ("weekly", "monthly", "quarterly", "daily", "yearly"))
+        and " by " not in text
+    ):
+        return "kpi"
+    if any(word in text for word in (" by ", "breakdown", "segment", "region", "channel", "product", "store")):
+        return "breakdown"
+    if chart_type in {"LINE", "AREA", "STACKED_AREA", "ADVANCED_LINE", "ADVANCED_STACKED_AREA"}:
+        return "trend"
+    if any(word in text for word in ("top ", "bottom ", "rank", "best ", "worst ")):
+        return "ranking"
+    return "driver"
+
+
+def _chunks(values: List[str], size: int) -> Iterable[List[str]]:
+    for index in range(0, len(values), size):
+        yield values[index:index + size]
+
+
+def _chunked_group_name(name: str, index: int) -> str:
+    if index == 0:
+        return name
+    if name == "Operational Breakdowns":
+        return "Additional Breakdowns"
+    if name == "Top Opportunities":
+        return "Additional Opportunities"
+    return f"{name} {index + 1}"
+
+
+def _chart_type(viz: Dict[str, Any]) -> str:
+    if "note_tile" in viz:
+        return "NOTE"
+    return str(viz.get("answer", {}).get("chart", {}).get("type", "UNKNOWN")).upper()
+
+
+def _section_description(name: str, tab: str) -> str:
+    if tab == EXECUTIVE_TAB:
+        return f"{name} for executive review"
+    return f"{name} for manager follow-up"

docs/liveboard_lab.md

@@ -0,0 +1,71 @@
+# Liveboard Lab
+
+The Liveboard Lab is an internal workflow for iterating on liveboard quality
+from existing ThoughtSpot model IDs. It preserves the supported architecture:
+
+1. MCP creates answers and the initial liveboard.
+2. TML post-processing polishes the same liveboard.
+3. The lab opts into the experimental `golden_two_tab` layout strategy.
+
+The normal app path is not changed by the lab. Production enhancement still
+defaults to the existing single-tab layout unless `layout_strategy` is passed.
+
+## Plan Only
+
+```bash
+python3 tools/liveboard_lab.py plan \
+  --company Nike \
+  --use-case "Retail Sales" \
+  --target-viz-count 16
+```
+
+This prints the dashboard plan without importing Snowflake or connecting to
+ThoughtSpot.
+
+## Create From Existing Model
+
+```bash
+python3 tools/liveboard_lab.py create \
+  --model-id "<thoughtspot-model-guid>" \
+  --model-name "<thoughtspot-model-name>" \
+  --company Nike \
+  --use-case "Retail Sales" \
+  --target-viz-count 16
+```
+
+Required ThoughtSpot settings can be passed as CLI flags or environment
+variables:
+
+- `THOUGHTSPOT_URL`
+- `THOUGHTSPOT_USERNAME`
+- `THOUGHTSPOT_TRUSTED_AUTH_KEY`
+
+For older DemoPrep `.env` files that use `TS_ENV_1_URL`, `TS_ENV_1_KEY_VAR`,
+and `TEST_USER`, pass:
+
+```bash
+python3 tools/liveboard_lab.py --env-file /path/to/.env --ts-env-index 1 create ...
+```
+
+## Re-Enhance Existing Liveboard
+
+```bash
+python3 tools/liveboard_lab.py enhance-existing \
+  --liveboard-guid "<thoughtspot-liveboard-guid>" \
+  --company Nike \
+  --use-case "Retail Sales"
+```
+
+Use this when MCP already created a liveboard and the iteration is only on TML
+layout/style.
+
+## Current Golden Target
+
+The reference is `goldendemo/Vizio.com.liveboard.tml`.
+
+The lab target is smaller than the reference:
+
+- 14-20 visualizations instead of 40+
+- 2 tabs: `Executive Overview`, `Operational Detail`
+- Thematic groups inspired by the reference
+- Curved borders, group colors, highlighted KPI tiles

liveboard_creator.py

@@ -19,6 +19,10 @@ import re
 import requests
 from typing import Dict, List, Optional
 from llm_config import DEFAULT_LLM_MODEL, map_llm_display_to_provider
+from demoprep_app.liveboards.blueprint import (
+    apply_blueprint_to_liveboard_tml,
+    build_liveboard_blueprint,
+)
 
 from dotenv import load_dotenv
 
@@ -636,13 +640,126 @@ def create_branded_note_tile(company_data: Dict, use_case: str, answers: List[Di
     company_name = company_data.get('name', 'Company')
     use_case_display = use_case if use_case else company_data.get('use_case', 'Analytics')
     viz_count = len(answers)
+    logo_url = company_data.get('logo_url', '').strip()
+    app_name = company_data.get('app_name', 'DemoPrep')
+
+    logo_block = ""
+    if logo_url:
+        logo_block = (
+            f'<div style="background:#ffffff; border-radius:10px; padding:14px 16px; '
+            f'margin-bottom:18px; text-align:left;">'
+            f'<img src="{logo_url}" alt="{company_name}" '
+            f'style="display:block; max-width:100%; width:310px; height:auto;" />'
+            f'</div>'
+        )
     
-    # Cleaner note tile - simpler format like golden demo
-    note_tile = f"""<h2 class="theme-module__editor-h2" dir="ltr"><span style="color: rgb(255, 255, 255); white-space: pre-wrap;">{company_name} {use_case_display}</span></h2><hr><p class="theme-module__editor-paragraph" dir="ltr"><span style="color: rgb(255, 255, 255); white-space: pre-wrap;">Featuring </span><b><strong class="theme-module__editor-text-bold" style="color: rgb(64, 193, 192); white-space: pre-wrap;">{viz_count} visualizations</strong></b><span style="color: rgb(255, 255, 255); white-space: pre-wrap;"> powered by ThoughtSpot AI</span></p><p class="theme-module__editor-paragraph"><br></p><p class="theme-module__editor-paragraph" dir="ltr"><span style="color: rgb(255, 255, 255); white-space: pre-wrap;">Built with </span><b><strong class="theme-module__editor-text-bold" style="color: rgb(64, 193, 192); white-space: pre-wrap;">Demo Wire</strong></b></p>"""
+    note_tile = f"""<div style="background:#0f1115; color:#ffffff; border-radius:14px; padding:22px 24px; font-family:Inter, Arial, sans-serif; min-height:250px; box-sizing:border-box;">
+{logo_block}
+<div style="font-size:12px; line-height:1; letter-spacing:2px; text-transform:uppercase; color:#40c1c0; font-weight:700; margin-bottom:10px;">{use_case_display}</div>
+<h2 class="theme-module__editor-h2" dir="ltr" style="margin:0 0 12px 0;"><span style="color:#ffffff; white-space:pre-wrap;">{company_name}</span></h2>
+<p class="theme-module__editor-paragraph" dir="ltr" style="margin:0 0 16px 0;"><span style="color:#d6dde8; white-space:pre-wrap;">Executive-ready analytics built from the live ThoughtSpot model, with KPI context and drilldowns for follow-up action.</span></p>
+<div style="display:flex; gap:10px; flex-wrap:wrap; margin-top:16px;">
+<span style="display:inline-block; background:#40c1c0; color:#071013; border-radius:999px; padding:7px 10px; font-size:12px; font-weight:700;">{viz_count} visualizations</span>
+<span style="display:inline-block; background:#202833; color:#ffffff; border:1px solid #40c1c0; border-radius:999px; padding:7px 10px; font-size:12px; font-weight:700;">ThoughtSpot AI</span>
+<span style="display:inline-block; background:#202833; color:#ffffff; border:1px solid #40c1c0; border-radius:999px; padding:7px 10px; font-size:12px; font-weight:700;">{app_name}</span>
+</div>
+</div>"""
     
     return note_tile
 
 
+def _apply_varied_chart_series_colors(visualizations: List[Dict]) -> int:
+    """Apply explicit series colors so MCP-created boards do not default to all blue."""
+    palettes = [
+        ['#A67F31', '#231F20', '#D6C28D', '#70551F'],
+        ['#06BF7F', '#48D1E0', '#2E75F0', '#2359B6'],
+        ['#8C62F5', '#D66EFA', '#F45BA8', '#7B61FF'],
+        ['#FF8142', '#FCC838', '#F7A11A', '#B06C00'],
+        ['#40C1C0', '#2458C9', '#6AA6FF', '#0B8FA3'],
+        ['#E05252', '#FFB84D', '#8C62F5', '#06BF7F'],
+        ['#2E75F0', '#F45BA8', '#FCC838', '#40C1C0'],
+        ['#6B7280', '#A67F31', '#111827', '#D1A84B'],
+        ['#00A3A3', '#7B61FF', '#FF8142', '#06BF7F'],
+        ['#B83280', '#2E75F0', '#F7A11A', '#48D1E0'],
+        ['#4B5563', '#10B981', '#F59E0B', '#6366F1'],
+    ]
+    updated_count = 0
+
+    for viz in visualizations:
+        answer = viz.get('answer', {})
+        chart = answer.get('chart', {})
+        chart_type = str(chart.get('type', '')).upper()
+        if not chart or chart_type in {'KPI', 'NOTE', ''}:
+            continue
+
+        palette = palettes[updated_count % len(palettes)]
+        client_state = _load_client_state(chart)
+        chart_properties = client_state.setdefault('chartProperties', {})
+        chart_properties['chartLevelColorConfig'] = {'colorPalette': {'colors': palette}}
+        chart_properties['seriesColorConfig'] = {'colors': palette}
+        chart_properties.setdefault('chartSpecific', {}).setdefault('dataFieldArea', 'column')
+
+        series_columns = _client_state_measure_columns(client_state)
+        if not series_columns:
+            series_columns = _chart_measure_columns(chart)
+        if not series_columns:
+            series_columns = ['Measure Values', answer.get('name', 'Value')]
+
+        series_colors = [
+            {'serieName': column, 'color': palette[index % len(palette)]}
+            for index, column in enumerate(series_columns)
+        ]
+        client_state['seriesColors'] = series_colors
+        client_state['systemSeriesColors'] = series_colors
+
+        if chart_type == 'HEATMAP':
+            chart_properties['heatmapColorConfig'] = {
+                'colorMap': [{'color': palette}],
+                'colorPalette': {'colors': palette},
+            }
+
+        chart['client_state_v2'] = json.dumps(client_state, separators=(',', ':'))
+        updated_count += 1
+
+    return updated_count
+
+
+def _load_client_state(chart: Dict) -> Dict:
+    try:
+        return json.loads(chart.get('client_state_v2') or '{}')
+    except Exception:
+        return {}
+
+
+def _client_state_measure_columns(client_state: Dict) -> List[str]:
+    columns = []
+    for axis in client_state.get('axisProperties', []) or []:
+        properties = axis.get('properties', {}) if isinstance(axis, dict) else {}
+        if properties.get('axisType') != 'Y':
+            continue
+        for column in properties.get('linkedColumns', []) or []:
+            if column not in columns:
+                columns.append(column)
+    return columns
+
+
+def _chart_measure_columns(chart: Dict) -> List[str]:
+    columns = []
+    for column in chart.get('chart_columns', []) or []:
+        if isinstance(column, dict):
+            name = column.get('column_id') or column.get('name') or column.get('id')
+        else:
+            name = str(column)
+        if not name:
+            continue
+        lowered = str(name).lower()
+        if any(token in lowered for token in ('date', 'month(', 'week(', 'quarter(', 'year(')):
+            continue
+        if name not in columns:
+            columns.append(str(name))
+    return columns
+
+
 class QueryTranslator:
     """Translate natural language queries to ThoughtSpot search syntax"""
 
@@ -3324,6 +3441,21 @@ def create_liveboard_from_model_mcp(
                             'success': False,
                             'error': 'Failed to get answers for any questions. Model may not contain data.'
                         }
+
+                    valid_answers = [
+                        ans for ans in answers
+                        if ans.get('session_identifier') and ans.get('tokens')
+                    ]
+                    dropped_answers = len(answers) - len(valid_answers)
+                    if dropped_answers:
+                        print(f"⚠️  Dropping {dropped_answers} answer(s) without session/tokens before createLiveboard", flush=True)
+                        answers = valid_answers
+
+                    if not answers:
+                        return {
+                            'success': False,
+                            'error': 'No valid answers with ThoughtSpot session/tokens were retrieved.'
+                        }
                     
                     print(f"✅ Successfully retrieved {len(answers)} answers")
                     
@@ -3590,12 +3722,17 @@ def create_liveboard_from_model_mcp(
                                         })
                                         print(f"   ✓ Added dark theme style to Viz_1")
                                     
-                                    # Convert time-series visualizations to KPIs with sparklines
+                                    # Convert only simple single-metric time-series visualizations
+                                    # to KPI cards. Multi-metric trends should remain charts, and
+                                    # executive pages should not become a wall of KPI tiles.
                                     print(f"   🔄 Converting time-series charts to KPIs...")
                                     kpi_count = 0
+                                    max_kpi_cards = 3
                                     for viz in visualizations:
                                         if viz.get('id') == 'Viz_1':
                                             continue  # Skip note tile
+                                        if kpi_count >= max_kpi_cards:
+                                            break
                                         
                                         answer = viz.get('answer', {})
                                         viz_name = answer.get('name', '').lower()
@@ -3604,8 +3741,14 @@ def create_liveboard_from_model_mcp(
                                         # Check if this is a time-series viz (weekly, monthly, daily patterns)
                                         time_patterns = ['weekly', 'monthly', 'daily', 'quarterly', 'yearly', '.week', '.month', '.day', '.quarter', '.year']
                                         is_time_series = any(p in viz_name or p in search_query for p in time_patterns)
+                                        is_multi_metric = (
+                                            ' and ' in viz_name
+                                            or ' vs ' in viz_name
+                                            or ' and ' in search_query
+                                            or ' vs ' in search_query
+                                        )
                                         
-                                        if is_time_series and 'chart' in answer:
+                                        if is_time_series and not is_multi_metric and 'chart' in answer:
                                             # Convert to KPI
                                             answer['chart']['type'] = 'KPI'
                                             
@@ -3640,6 +3783,20 @@ def create_liveboard_from_model_mcp(
                                     
                                     if kpi_count > 0:
                                         print(f"   ✅ Converted {kpi_count} visualizations to KPIs with sparklines")
+
+                                    palette_count = _apply_varied_chart_series_colors(visualizations)
+                                    if palette_count > 0:
+                                        print(f"   🎨 Applied varied colors to {palette_count} chart visualizations")
+
+                                    blueprint = build_liveboard_blueprint(
+                                        company_data=company_data,
+                                        use_case=use_case or company_data.get('use_case', 'Analytics'),
+                                        model_columns=model_columns or [],
+                                        target_filter_count=3,
+                                    )
+                                    liveboard_tml, blueprint_changes = apply_blueprint_to_liveboard_tml(liveboard_tml, blueprint)
+                                    for change in blueprint_changes:
+                                        print(f"   🧭 {change}")
                                     
                                     # Re-import fixed TML using authenticated session
                                     import_response = ts_client.session.post(
@@ -3778,7 +3935,8 @@ def enhance_mcp_liveboard(
     fix_kpis: bool = True,
     apply_brand_colors: bool = True,
     add_layout: bool = True,
-    llm_model: str = None
+    llm_model: str = None,
+    layout_strategy: str = "single_tab",
 ) -> Dict:
     """
     Enhance an MCP-created liveboard with TML post-processing (Golden Demo style).
@@ -3803,6 +3961,8 @@ def enhance_mcp_liveboard(
         fix_kpis: Whether to fix KPI visualizations for sparklines
         apply_brand_colors: Whether to apply brand color styling
         add_layout: Whether to add proper tab/tile layout
+        layout_strategy: "single_tab" preserves existing app behavior;
+            "golden_two_tab" applies the lab's golden-demo-inspired layout.
     
     Returns:
         Dict with success, message, enhancements list
@@ -3901,30 +4061,35 @@ def enhance_mcp_liveboard(
                 other_vizs.append(viz_id)
         
         print(f"  Classification: {len(kpi_vizs)} KPIs, {len(trend_vizs)} trends, {len(bar_vizs)} bars, {len(table_vizs)} tables, {len(note_vizs)} notes", flush=True)
+
+        use_golden_two_tab = layout_strategy == "golden_two_tab"
         
         # Step 2.5: Remove note tiles (MCP requires them but we don't want them in final liveboard)
         # Safety: only remove note tiles if there are other vizzes to show — never leave liveboard empty
         non_note_count = len(visualizations) - len(note_vizs)
-        if note_vizs and non_note_count > 0:
+        if note_vizs and non_note_count > 0 and not use_golden_two_tab:
             print(f"  Removing {len(note_vizs)} note tile(s)...", flush=True)
             original_count = len(visualizations)
+            removed_note_count = len(note_vizs)
             liveboard_tml['liveboard']['visualizations'] = [
                 v for v in visualizations if v.get('id') not in note_vizs
             ]
             visualizations = liveboard_tml['liveboard']['visualizations']
+            note_vizs = []
             print(f"  [OK] Removed note tiles ({original_count} -> {len(visualizations)} visualizations)", flush=True)
-            enhancements_applied.append(f"Removed {len(note_vizs)} note tile(s)")
+            enhancements_applied.append(f"Removed {removed_note_count} note tile(s)")
         elif note_vizs and non_note_count == 0:
             print(f"  ⚠️  Only note tiles found ({len(note_vizs)}) — MCP may have returned no chart answers. Keeping note tiles to preserve liveboard content.", flush=True)
-        
+
         # Step 3: Add Groups - simplified: just KPI section, rest ungrouped
         if add_groups:
-            print(f"  Adding Groups (simplified)...", flush=True)
+            print(f"  Adding Groups ({'golden two-tab later' if use_golden_two_tab else 'simplified'})...", flush=True)
             
             groups = []
             
-            # Create ONE group: Key Metrics with ALL KPIs (always at top)
-            if kpi_vizs:
+            # Create ONE group: Key Metrics with ALL KPIs (always at top).
+            # Golden two-tab mode replaces this with thematic groups during layout.
+            if kpi_vizs and not use_golden_two_tab:
                 groups.append({
                     'id': 'Group_1',
                     'name': 'Key Metrics',
@@ -3981,7 +4146,7 @@ def enhance_mcp_liveboard(
                 print(f"  [OK] Converted {converted_count} LINE→KPI", flush=True)
                 
                 # Update the groups if we just created KPIs
-                if add_groups and 'groups' in liveboard_tml.get('liveboard', {}):
+                if add_groups and not use_golden_two_tab and 'groups' in liveboard_tml.get('liveboard', {}):
                     groups = liveboard_tml['liveboard']['groups']
                     if not groups:  # No groups yet
                         groups.append({
@@ -4120,6 +4285,11 @@ def enhance_mcp_liveboard(
         if stacked_converted > 0:
             enhancements_applied.append(f"Converted {stacked_converted} charts to stacked column")
             print(f"  [OK] Converted {stacked_converted} charts to stacked column", flush=True)
+
+        palette_count = _apply_varied_chart_series_colors(visualizations)
+        if palette_count > 0:
+            enhancements_applied.append(f"Applied varied palettes to {palette_count} chart(s)")
+            print(f"  [OK] Applied varied palettes to {palette_count} chart(s)", flush=True)
         
         # Step 5: Apply brand colors and styling (Golden Demo style)
         if apply_brand_colors:
@@ -4177,16 +4347,17 @@ def enhance_mcp_liveboard(
                     colors_applied += 1
             
             # Style note tiles
-            for note_id in note_vizs:
-                existing = next((o for o in style['overrides'] if o.get('object_id') == note_id), None)
-                if not existing:
-                    style['overrides'].append({
-                        'object_id': note_id,
-                        'style_properties': [
-                            {'name': 'tile_brand_color', 'value': 'TBC_I'}
-                        ]
-                    })
-                    colors_applied += 1
+            if not use_golden_two_tab:
+                for note_id in note_vizs:
+                    existing = next((o for o in style['overrides'] if o.get('object_id') == note_id), None)
+                    if not existing:
+                        style['overrides'].append({
+                            'object_id': note_id,
+                            'style_properties': [
+                                {'name': 'tile_brand_color', 'value': 'TBC_I'}
+                            ]
+                        })
+                        colors_applied += 1
             
             # Hide descriptions on analysis charts
             for viz_id in (bar_vizs + table_vizs + other_vizs):
@@ -4206,85 +4377,99 @@ def enhance_mcp_liveboard(
         # Step 6: Add proper layout with tabs and group_layouts (Golden Demo style)
         if add_layout:
             print(f"  Adding layout structure (tab-based with group_layouts)...", flush=True)
-            
-            groups = liveboard_tml.get('liveboard', {}).get('groups', [])
-            all_viz_ids = kpi_vizs + trend_vizs + bar_vizs + geo_vizs + table_vizs + other_vizs
-            
-            # Collect grouped visualization IDs
-            grouped_vizs = set()
-            for group in groups:
-                grouped_vizs.update(group.get('visualizations', []))
-            
-            # Ungrouped visualizations (everything not in a group)
-            ungrouped = [v for v in all_viz_ids if v not in grouped_vizs]
-            
-            # === Build tab tiles: groups FIRST (KPIs at top), then ungrouped below ===
-            tab_tiles = []
-            row = 0
-            
-            # Add KPI group at the very top spanning full width
-            for group in groups:
-                grp_id = group.get('id')
-                grp_vizs = group.get('visualizations', [])
-                # KPI group spans full width at top
-                group_height = max(3, (len(grp_vizs) + 1) // 2 * 3)  # 3 rows per pair
-                tab_tiles.append({
-                    'visualization_id': grp_id,
-                    'x': 0,
-                    'y': row,
-                    'height': group_height,
-                    'width': 12  # Full width for KPI group
-                })
-                row += group_height
-            
-            # Add ungrouped visualizations in 2-column grid below groups
-            for i, viz_id in enumerate(ungrouped):
-                tab_tiles.append({
-                    'visualization_id': viz_id,
-                    'x': 0 if i % 2 == 0 else 6,
-                    'y': row + (i // 2) * 5,
-                    'height': 5,
-                    'width': 6
-                })
-            
-            # === Build group_layouts: define tile positions INSIDE each group ===
-            group_layouts = []
-            for group in groups:
-                grp_id = group.get('id')
-                grp_vizs = group.get('visualizations', [])
-                
-                grp_tiles = []
-                for j, gviz_id in enumerate(grp_vizs):
-                    # KPIs: 2-column layout inside group, each 3 rows tall
-                    grp_tiles.append({
-                        'visualization_id': gviz_id,
-                        'x': 0 if j % 2 == 0 else 6,
-                        'y': (j // 2) * 3,
-                        'height': 3,
+            if use_golden_two_tab:
+                from demoprep_app.liveboards.golden_layout import (
+                    apply_golden_two_tab_layout,
+                    build_dashboard_plan,
+                )
+
+                plan = build_dashboard_plan(
+                    company_name=company_data.get('name', 'Company'),
+                    use_case=company_data.get('use_case') or company_data.get('use_case_name') or 'Analytics',
+                    target_viz_count=len(visualizations),
+                )
+                liveboard_tml, golden_changes = apply_golden_two_tab_layout(liveboard_tml, plan)
+                enhancements_applied.extend(golden_changes)
+                print(f"  [OK] Applied golden two-tab layout", flush=True)
+            else:
+                groups = liveboard_tml.get('liveboard', {}).get('groups', [])
+                all_viz_ids = kpi_vizs + trend_vizs + bar_vizs + geo_vizs + table_vizs + other_vizs
+
+                # Collect grouped visualization IDs
+                grouped_vizs = set()
+                for group in groups:
+                    grouped_vizs.update(group.get('visualizations', []))
+
+                # Ungrouped visualizations (everything not in a group)
+                ungrouped = [v for v in all_viz_ids if v not in grouped_vizs]
+
+                # === Build tab tiles: groups FIRST (KPIs at top), then ungrouped below ===
+                tab_tiles = []
+                row = 0
+
+                # Add KPI group at the very top spanning full width
+                for group in groups:
+                    grp_id = group.get('id')
+                    grp_vizs = group.get('visualizations', [])
+                    # KPI group spans full width at top
+                    group_height = max(3, (len(grp_vizs) + 1) // 2 * 3)  # 3 rows per pair
+                    tab_tiles.append({
+                        'visualization_id': grp_id,
+                        'x': 0,
+                        'y': row,
+                        'height': group_height,
+                        'width': 12  # Full width for KPI group
+                    })
+                    row += group_height
+
+                # Add ungrouped visualizations in 2-column grid below groups
+                for i, viz_id in enumerate(ungrouped):
+                    tab_tiles.append({
+                        'visualization_id': viz_id,
+                        'x': 0 if i % 2 == 0 else 6,
+                        'y': row + (i // 2) * 5,
+                        'height': 5,
                         'width': 6
                     })
-                
-                group_layouts.append({
-                    'id': grp_id,
-                    'tiles': grp_tiles
-                })
-            
-            # === Assemble the layout with tabs structure ===
-            if tab_tiles:
-                tab = {
-                    'name': 'Overview',
-                    'description': '',
-                    'tiles': tab_tiles
-                }
-                if group_layouts:
-                    tab['group_layouts'] = group_layouts
-                
-                liveboard_tml['liveboard']['layout'] = {
-                    'tabs': [tab]
-                }
-                total_tiles = len(tab_tiles) + sum(len(gl.get('tiles', [])) for gl in group_layouts)
-                enhancements_applied.append(f"Added tab layout ({total_tiles} tiles, {len(group_layouts)} group layouts)")
-                print(f"  [OK] Added tab layout: {len(tab_tiles)} top-level tiles, {len(group_layouts)} group layouts", flush=True)
+
+                # === Build group_layouts: define tile positions INSIDE each group ===
+                group_layouts = []
+                for group in groups:
+                    grp_id = group.get('id')
+                    grp_vizs = group.get('visualizations', [])
+
+                    grp_tiles = []
+                    for j, gviz_id in enumerate(grp_vizs):
+                        # KPIs: 2-column layout inside group, each 3 rows tall
+                        grp_tiles.append({
+                            'visualization_id': gviz_id,
+                            'x': 0 if j % 2 == 0 else 6,
+                            'y': (j // 2) * 3,
+                            'height': 3,
+                            'width': 6
+                        })
+
+                    group_layouts.append({
+                        'id': grp_id,
+                        'tiles': grp_tiles
+                    })
+
+                # === Assemble the layout with tabs structure ===
+                if tab_tiles:
+                    tab = {
+                        'name': 'Overview',
+                        'description': '',
+                        'tiles': tab_tiles
+                    }
+                    if group_layouts:
+                        tab['group_layouts'] = group_layouts
+
+                    liveboard_tml['liveboard']['layout'] = {
+                        'tabs': [tab]
+                    }
+                    total_tiles = len(tab_tiles) + sum(len(gl.get('tiles', [])) for gl in group_layouts)
+                    enhancements_applied.append(f"Added tab layout ({total_tiles} tiles, {len(group_layouts)} group layouts)")
+                    print(f"  [OK] Added tab layout: {len(tab_tiles)} top-level tiles, {len(group_layouts)} group layouts", flush=True)
         
         # Step 6.5: Humanize viz titles via LLM
         print(f"  Humanizing viz titles...", flush=True)
@@ -4319,6 +4504,18 @@ def enhance_mcp_liveboard(
                     enhancements_applied.append(f"Humanized {_titles_updated} viz titles")
                     print(f"  [OK] Applied humanized titles to {_titles_updated} vizzes", flush=True)
 
+        blueprint = build_liveboard_blueprint(
+            company_data=company_data,
+            use_case=company_data.get('use_case', 'Analytics'),
+            model_columns=company_data.get('model_columns', []),
+            target_filter_count=3,
+        )
+        liveboard_tml, blueprint_changes = apply_blueprint_to_liveboard_tml(liveboard_tml, blueprint)
+        if blueprint_changes:
+            enhancements_applied.extend(blueprint_changes)
+            for change in blueprint_changes:
+                print(f"  [OK] {change}", flush=True)
+
         # Step 7: Re-import the enhanced TML
         if enhancements_applied:
             print(f"  Re-importing enhanced TML...", flush=True)

tests/test_golden_layout.py

@@ -0,0 +1,186 @@
+import yaml
+
+from demoprep_app.liveboards.golden_layout import (
+    EXECUTIVE_TAB,
+    OPERATIONS_TAB,
+    apply_golden_two_tab_layout,
+    build_dashboard_plan,
+    summarize_liveboard_tml,
+)
+
+
+def test_dashboard_plan_has_two_audiences_and_bounded_count():
+    plan = build_dashboard_plan("Nike", "Retail Sales", target_viz_count=99)
+
+    assert plan["target_viz_count"] == 24
+    assert [audience["tab"] for audience in plan["audiences"]] == [
+        EXECUTIVE_TAB,
+        "Sales Management",
+    ]
+    assert plan["sections"][0]["name"] == "Key Performance Metrics"
+
+
+def test_apply_golden_two_tab_layout_groups_and_styles_synthetic_tml():
+    tml = {
+        "liveboard": {
+            "name": "Lab Liveboard",
+            "visualizations": [
+                _viz("Viz_1", "Total Revenue", "KPI", "sum [Revenue] [Date].monthly"),
+                _viz("Viz_2", "Total Orders", "KPI", "sum [Orders] [Date].monthly"),
+                _viz("Viz_3", "Revenue Trend", "LINE", "sum [Revenue] by [Date].monthly"),
+                _viz("Viz_4", "Revenue by Region", "COLUMN", "sum [Revenue] by [Region]"),
+                _viz("Viz_5", "Top Stores by Revenue", "BAR", "top 10 [Store] by [Revenue]"),
+                _viz("Viz_6", "Store Detail", "TABLE", "[Store] [Revenue] [Orders]"),
+                {"id": "Viz_7", "note_tile": {"text": "remove me"}},
+            ],
+        }
+    }
+
+    updated, changes = apply_golden_two_tab_layout(tml, build_dashboard_plan("Nike", "Retail Sales", 16))
+    summary = summarize_liveboard_tml(updated)
+
+    assert "Applied golden two-tab layout" in changes[0]
+    assert summary["visualization_count"] == 7
+    assert summary["tab_names"] == [EXECUTIVE_TAB, "Sales Management"]
+    assert "Key Performance Metrics" in summary["group_names"]
+    assert updated["liveboard"]["visualizations"][-1]["note_tile"]["html_parsed_string"]
+    assert updated["liveboard"]["style"]["style_properties"]
+    assert any(
+        override["object_id"] == "Viz_1"
+        for override in updated["liveboard"]["style"]["overrides"]
+    )
+    executive_tiles = updated["liveboard"]["layout"]["tabs"][0]["tiles"]
+    assert executive_tiles[0]["visualization_id"] == "Viz_7"
+    assert executive_tiles[0]["x"] == 0
+    assert executive_tiles[1]["visualization_id"] == "Group_1"
+    assert executive_tiles[1]["x"] == 3
+
+
+def test_dimensional_line_charts_move_to_manager_tab():
+    tml = {
+        "liveboard": {
+            "name": "Lab Liveboard",
+            "visualizations": [
+                _viz("Viz_1", "Total Revenue", "KPI", "sum [Revenue] [Date].monthly"),
+                _viz(
+                    "Viz_2",
+                    "Utilization by Region and Seniority",
+                    "ADVANCED_LINE",
+                    "sum [Utilization] by [Region] [Seniority]",
+                ),
+                _viz("Viz_3", "Revenue by Region", "COLUMN", "sum [Revenue] by [Region]"),
+            ],
+        }
+    }
+
+    updated, _changes = apply_golden_two_tab_layout(
+        tml,
+        build_dashboard_plan("EY", "Professional Services", 16),
+    )
+    tabs = updated["liveboard"]["layout"]["tabs"]
+
+    assert tabs[0]["name"] == EXECUTIVE_TAB
+    assert tabs[1]["name"] == "Practice Management"
+    assert "Viz_2" not in _tab_viz_ids(tabs[0])
+    assert "Viz_2" in _tab_viz_ids(tabs[1])
+
+
+def test_chart_palettes_include_explicit_series_colors():
+    tml = {
+        "liveboard": {
+            "name": "Lab Liveboard",
+            "visualizations": [
+                _viz(
+                    "Viz_1",
+                    "Revenue by Region",
+                    "COLUMN",
+                    "sum [Revenue] by [Region]",
+                    chart_columns=[
+                        {"column_id": "Region"},
+                        {"column_id": "Total Revenue"},
+                    ],
+                ),
+            ],
+        }
+    }
+
+    updated, _changes = apply_golden_two_tab_layout(tml, build_dashboard_plan("Nike", "Retail Sales", 16))
+    client_state = updated["liveboard"]["visualizations"][0]["answer"]["chart"]["client_state_v2"]
+
+    assert "seriesColors" in client_state
+    assert "Total Revenue" in client_state
+    assert "#06BF7F" in client_state
+
+
+def test_periodic_metric_lines_become_real_kpi_charts():
+    tml = {
+        "liveboard": {
+            "name": "Lab Liveboard",
+            "visualizations": [
+                _viz(
+                    "Viz_1",
+                    "Total Weekly Revenue",
+                    "ADVANCED_LINE",
+                    "sum [Revenue] [Date].weekly",
+                    answer_columns=[
+                        {"name": "Total Revenue"},
+                        {"name": "Week(Date)"},
+                    ],
+                    chart_columns=[
+                        {"column_id": "Total Revenue"},
+                        {"column_id": "Week(Date)"},
+                    ],
+                ),
+                _viz("Viz_2", "Revenue by Region", "COLUMN", "sum [Revenue] by [Region]"),
+            ],
+        }
+    }
+
+    updated, changes = apply_golden_two_tab_layout(tml, build_dashboard_plan("Nike", "Retail Sales", 16))
+    chart = updated["liveboard"]["visualizations"][0]["answer"]["chart"]
+
+    assert "Converted 1 periodic metric chart(s) to KPI" in changes
+    assert chart["type"] == "KPI"
+    assert chart["axis_configs"] == [{"x": ["Week(Date)"], "y": ["Total Revenue"]}]
+    assert chart["chart_columns"] == [
+        {"column_id": "Week(Date)"},
+        {"column_id": "Total Revenue"},
+    ]
+
+
+def test_golden_demo_summary_captures_reference_shape():
+    with open("goldendemo/Vizio.com.liveboard.tml", "r", encoding="utf-8") as fh:
+        # ThoughtSpot exports unquoted YAML tokens such as `oper: =`.
+        # BaseLoader keeps this test focused on exported structure.
+        tml = yaml.load(fh, Loader=yaml.BaseLoader)
+
+    summary = summarize_liveboard_tml(tml)
+
+    assert summary["visualization_count"] >= 40
+    assert summary["group_count"] == 18
+    assert summary["tab_names"][0] == "Overview"
+    assert "Forecasting" in summary["tab_names"]
+
+
+def _viz(viz_id, name, chart_type, query, answer_columns=None, chart_columns=None):
+    return {
+        "id": viz_id,
+        "answer": {
+            "name": name,
+            "search_query": query,
+            "answer_columns": answer_columns or [],
+            "chart": {"type": chart_type, "chart_columns": chart_columns or []},
+        },
+    }
+
+
+def _tab_viz_ids(tab):
+    group_ids = {layout["id"]: layout for layout in tab.get("group_layouts", [])}
+    ids = set()
+    for tile in tab.get("tiles", []):
+        tile_id = tile.get("visualization_id")
+        if tile_id in group_ids:
+            ids.update(inner.get("visualization_id") for inner in group_ids[tile_id].get("tiles", []))
+        else:
+            ids.add(tile_id)
+    return ids

tests/test_liveboard_blueprint.py

@@ -0,0 +1,84 @@
+from demoprep_app.liveboards.blueprint import (
+    DEMO_GUIDE_VIZ_ID,
+    apply_blueprint_to_liveboard_tml,
+    build_liveboard_blueprint,
+    choose_global_filters,
+)
+
+
+def test_choose_global_filters_prefers_business_fields_and_clean_names():
+    columns = [
+        {"name": "Prog Program Key", "type": "ATTRIBUTE"},
+        {"name": "Program Name", "type": "ATTRIBUTE"},
+        {"name": "Campus Name", "type": "ATTRIBUTE"},
+        {"name": "Student Segment Name", "type": "ATTRIBUTE"},
+        {"name": "Scenario Category", "type": "ATTRIBUTE"},
+        {"name": "Applications", "type": "MEASURE"},
+        {"name": "Yield Rate Pct", "type": "MEASURE"},
+    ]
+
+    filters = choose_global_filters(columns, target_filter_count=3)
+
+    assert [flt["display_name"] for flt in filters] == [
+        "Program",
+        "Campus",
+        "Student Segment",
+    ]
+    assert all(flt["is_mandatory"] is False for flt in filters)
+    assert all("filter" not in flt for flt in filters)
+    assert all("date_filter" not in flt for flt in filters)
+
+
+def test_blueprint_demo_notes_use_demoprep_and_no_stale_copy():
+    blueprint = build_liveboard_blueprint(
+        {"name": "Wake Forest University", "research": "Enrollment leaders need a concise view."},
+        "Enrollment and Student Success Analytics",
+        [{"name": "Program Name", "type": "ATTRIBUTE"}, {"name": "Campus Name", "type": "ATTRIBUTE"}],
+    )
+
+    html = blueprint["demo_notes_tile"]["html"]
+
+    assert "DemoPrep" in html
+    assert "Demo Wire" not in html
+    assert "Wake Forest University" in html
+    assert "Program" in html
+
+
+def test_apply_blueprint_adds_filters_and_bottom_demo_tile():
+    tml = {
+        "liveboard": {
+            "name": "Test Board",
+            "visualizations": [
+                {"id": "Viz_1", "answer": {"name": "Applications", "chart": {"type": "KPI"}}},
+                {"id": "Viz_2", "answer": {"name": "Trend", "chart": {"type": "LINE"}}},
+            ],
+            "layout": {
+                "tabs": [
+                    {
+                        "name": "Executive Overview",
+                        "tiles": [
+                            {"visualization_id": "Viz_1", "x": 0, "y": 0, "height": 5, "width": 6},
+                            {"visualization_id": "Viz_2", "x": 6, "y": 0, "height": 5, "width": 6},
+                        ],
+                    }
+                ]
+            },
+        }
+    }
+    blueprint = {
+        "filters": [
+            {"column": ["Program Name"], "is_mandatory": False, "is_single_value": False, "display_name": "Program"}
+        ],
+        "demo_notes_tile": {"id": DEMO_GUIDE_VIZ_ID, "html": "<div>DemoPrep guide</div>"},
+    }
+
+    updated, changes = apply_blueprint_to_liveboard_tml(tml, blueprint)
+    liveboard = updated["liveboard"]
+
+    assert changes == ["Added 1 global filter(s)", "Added demo guide tile"]
+    assert liveboard["filters"][0]["display_name"] == "Program"
+    assert any(viz["id"] == DEMO_GUIDE_VIZ_ID for viz in liveboard["visualizations"])
+    demo_tile = liveboard["layout"]["tabs"][0]["tiles"][-1]
+    assert demo_tile["visualization_id"] == DEMO_GUIDE_VIZ_ID
+    assert demo_tile["y"] == 5
+    assert demo_tile["width"] == 12

tools/liveboard_lab.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Internal Liveboard Lab for faster MCP-first/TML-polish iteration.
+
+Examples:
+    python tools/liveboard_lab.py plan --company Nike --use-case "Retail Sales"
+
+    python tools/liveboard_lab.py create \
+      --model-id 00000000-0000-0000-0000-000000000000 \
+      --model-name NIKE_RETAIL_mdl \
+      --company Nike \
+      --use-case "Retail Sales"
+
+    python tools/liveboard_lab.py enhance-existing \
+      --liveboard-guid 00000000-0000-0000-0000-000000000000 \
+      --company Nike \
+      --use-case "Retail Sales"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+try:
+    from dotenv import load_dotenv
+except ImportError:  # pragma: no cover - dotenv is present in app envs
+    load_dotenv = None
+
+from demoprep_app.liveboards.golden_layout import build_dashboard_plan
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Create or re-enhance golden-demo-style liveboards from existing ThoughtSpot models."
+    )
+    parser.add_argument(
+        "--env-file",
+        default="",
+        help="Optional .env file to load before reading ThoughtSpot and LLM settings.",
+    )
+    parser.add_argument(
+        "--ts-env-index",
+        default="1",
+        help="Fallback TS_ENV_<n> environment index used by older DemoPrep .env files.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    plan_parser = subparsers.add_parser("plan", help="Print the dashboard plan only.")
+    _add_context_args(plan_parser)
+    plan_parser.add_argument("--target-viz-count", type=int, default=16)
+
+    create_parser = subparsers.add_parser("create", help="Create a liveboard from an existing model ID.")
+    _add_context_args(create_parser)
+    _add_auth_args(create_parser)
+    create_parser.add_argument("--model-id", required=True)
+    create_parser.add_argument("--model-name", required=True)
+    create_parser.add_argument("--target-viz-count", type=int, default=16)
+    create_parser.add_argument("--liveboard-name", default="")
+    create_parser.add_argument("--llm-model", default="")
+
+    enhance_parser = subparsers.add_parser(
+        "enhance-existing",
+        help="Apply the lab golden two-tab TML enhancement to an existing liveboard.",
+    )
+    _add_context_args(enhance_parser)
+    _add_auth_args(enhance_parser)
+    enhance_parser.add_argument("--liveboard-guid", required=True)
+    enhance_parser.add_argument("--llm-model", default="")
+
+    args = parser.parse_args()
+
+    if load_dotenv:
+        if args.env_file:
+            load_dotenv(args.env_file, override=False)
+        load_dotenv(REPO_ROOT / ".env", override=False)
+    _apply_legacy_ts_env(args.ts_env_index)
+
+    company_data = {
+        "name": args.company,
+        "website": args.website,
+        "research": args.research,
+        "additional_context": args.additional_context,
+        "use_case": args.use_case,
+    }
+
+    if args.command == "plan":
+        plan = build_dashboard_plan(args.company, args.use_case, args.target_viz_count)
+        print(json.dumps(plan, indent=2))
+        return 0
+
+    from liveboard_creator import create_liveboard_from_model_mcp, enhance_mcp_liveboard
+
+    ts_client = _build_ts_client(args)
+    if not ts_client.authenticate():
+        print("ThoughtSpot authentication failed.", file=sys.stderr)
+        return 2
+
+    if args.command == "enhance-existing":
+        result = enhance_mcp_liveboard(
+            liveboard_guid=args.liveboard_guid,
+            company_data=company_data,
+            ts_client=ts_client,
+            add_groups=True,
+            fix_kpis=True,
+            apply_brand_colors=True,
+            add_layout=True,
+            llm_model=args.llm_model or None,
+            layout_strategy="golden_two_tab",
+        )
+        print(json.dumps(result, indent=2))
+        return 0 if result.get("success") else 1
+
+    liveboard_name = args.liveboard_name.strip() or f"{args.company} - {args.use_case} Lab"
+    result = create_liveboard_from_model_mcp(
+        ts_client=ts_client,
+        model_id=args.model_id,
+        model_name=args.model_name,
+        company_data=company_data,
+        use_case=args.use_case,
+        num_visualizations=args.target_viz_count,
+        liveboard_name=liveboard_name,
+        llm_model=args.llm_model or None,
+    )
+
+    if not result.get("success"):
+        print(json.dumps(result, indent=2))
+        return 1
+
+    liveboard_guid = result.get("liveboard_guid") or result.get("liveboard_id")
+    if liveboard_guid:
+        enhance_result = enhance_mcp_liveboard(
+            liveboard_guid=liveboard_guid,
+            company_data=company_data,
+            ts_client=ts_client,
+            add_groups=True,
+            fix_kpis=True,
+            apply_brand_colors=True,
+            add_layout=True,
+            llm_model=args.llm_model or None,
+            layout_strategy="golden_two_tab",
+        )
+        result["lab_enhancement"] = enhance_result
+
+    print(json.dumps(result, indent=2))
+    return 0 if result.get("success") else 1
+
+
+def _add_context_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--company", required=True)
+    parser.add_argument("--use-case", required=True)
+    parser.add_argument("--website", default="")
+    parser.add_argument("--research", default="")
+    parser.add_argument("--additional-context", default="")
+
+
+def _add_auth_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--ts-url", default="")
+    parser.add_argument("--ts-username", default="")
+    parser.add_argument("--ts-secret-key", default="")
+
+
+def _apply_legacy_ts_env(index: str) -> None:
+    """Map older TS_ENV_<n> settings to the names the lab expects."""
+    if not os.getenv("THOUGHTSPOT_URL"):
+        os.environ["THOUGHTSPOT_URL"] = os.getenv(f"TS_ENV_{index}_URL", "")
+    if not os.getenv("THOUGHTSPOT_USERNAME"):
+        os.environ["THOUGHTSPOT_USERNAME"] = os.getenv("TEST_USER", "")
+    if not os.getenv("THOUGHTSPOT_TRUSTED_AUTH_KEY"):
+        key_value = os.getenv(f"TS_ENV_{index}_KEY_VAR", "")
+        if key_value:
+            os.environ["THOUGHTSPOT_TRUSTED_AUTH_KEY"] = os.getenv(key_value, key_value)
+
+
+def _build_ts_client(args: argparse.Namespace) -> Any:
+    missing = [
+        name
+        for name, value in {
+            "--ts-url or THOUGHTSPOT_URL": args.ts_url or os.getenv("THOUGHTSPOT_URL", ""),
+            "--ts-username or THOUGHTSPOT_USERNAME": args.ts_username or os.getenv("THOUGHTSPOT_USERNAME", ""),
+            "--ts-secret-key or THOUGHTSPOT_TRUSTED_AUTH_KEY": args.ts_secret_key or os.getenv("THOUGHTSPOT_TRUSTED_AUTH_KEY", ""),
+        }.items()
+        if not value
+    ]
+    if missing:
+        raise SystemExit(f"Missing ThoughtSpot settings: {', '.join(missing)}")
+    return LabThoughtSpotClient(
+        base_url=args.ts_url or os.getenv("THOUGHTSPOT_URL", ""),
+        username=args.ts_username or os.getenv("THOUGHTSPOT_USERNAME", ""),
+        secret_key=args.ts_secret_key or os.getenv("THOUGHTSPOT_TRUSTED_AUTH_KEY", ""),
+    )
+
+
+class LabThoughtSpotClient:
+    """Minimal ThoughtSpot client for liveboard lab flows only."""
+
+    def __init__(self, base_url: str, username: str, secret_key: str):
+        import requests
+
+        self.base_url = base_url.rstrip("/")
+        self.username = username
+        self.secret_key = secret_key
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Content-Type": "application/json",
+                "X-Requested-By": "ThoughtSpot",
+            }
+        )
+
+    def authenticate(self) -> bool:
+        response = self.session.post(
+            f"{self.base_url}/api/rest/2.0/auth/token/full",
+            json={
+                "username": self.username,
+                "secret_key": self.secret_key,
+                "validity_time_in_sec": 3600,
+            },
+        )
+        if response.status_code == 200:
+            payload = response.json()
+            token = payload.get("token")
+            if token:
+                self.session.headers["Authorization"] = f"Bearer {token}"
+            return True
+        if response.status_code == 204:
+            return True
+        print(f"ThoughtSpot auth failed: HTTP {response.status_code} {response.text[:300]}", file=sys.stderr)
+        return False
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())