feat(mcp): settings document on build_demo_from_brief replaces per-run Supabase settings reads

A separate TSE app owns an SE's DemoPrep settings and Agent Q hands them to the
build as one JSON document (schema 1.0, the `settings` keyword argument). When
present, the build takes model, data size, column naming style, object prefix,
liveboard name, tag, share-with and geo scope from it and reads nothing from the
SE's Supabase settings: the controller skips its startup read and the three
mid-run re-reads are guarded. Explicit owner_email / ts_url still win; a blank
ts_url falls back to the document's URL, then its environment label through the
TS_ENV table. A bad document is refused before a slot is taken, naming the key.

- demoprep_app/settings/payload.py: the one parser and apply step (the data-size
presets live here now)
- chat_interface: ChatDemoInterface(settings_from_supabase=...), _settings_source
- run record carries settings_source and settings_schema_version
- docs: settings inventory with decisions and the phase-2 Supabase scope, the
example document, the brief for the settings-app builder, the Agent Q flag
registry row, the sprint entry
- tests: test_settings_payload (30), test_mcp_settings_document (12); the two
signature-mirror tests and one loader stub updated for the new parameter

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

chat_interface.py

@@ -408,11 +408,17 @@ class ChatDemoInterface:
     New chat-based interface for demo creation
     """
     
-    def __init__(self, user_email: str = None):
+    def __init__(self, user_email: str = None, *, settings_from_supabase: bool = True):
         self.user_email = user_email  # Must be set by login system
         self.demo_builder = None
         self.conversation_history = []
-        self.settings = self.load_default_settings()
+        # Where this run's settings come from. 'supabase' = the per-key
+        # user_settings rows (App/Chat tabs, legacy MCP). 'payload' = a settings
+        # document the caller applies onto self.settings (MCP with `settings`);
+        # then NOTHING in the run reads Supabase settings, including the mid-run
+        # re-reads in run_deployment_streaming / _run_thoughtspot_deployment.
+        self._settings_source = 'supabase' if settings_from_supabase else 'payload'
+        self.settings = self.load_default_settings(from_supabase=settings_from_supabase)
         self.ai_feedback_log = []
         self.ddl_code = ""
         self.population_code = ""
@@ -685,8 +691,11 @@ class ChatDemoInterface:
             print(f"[Auth] Unable to check temporary-password status: {e}")
         return ""
     
-    def load_default_settings(self):
-        """Load settings from Supabase or defaults"""
+    def load_default_settings(self, from_supabase: bool = True):
+        """Load settings from Supabase or defaults.
+
+        from_supabase=False returns the built-in defaults only (the caller is
+        about to apply a settings document on top; see _settings_source)."""
         # Fallback defaults (ONLY used if settings not found)
         defaults = {
             'company': '',
@@ -700,6 +709,9 @@ class ChatDemoInterface:
             'geo_scope': 'USA Only',  # USA Only or International
         }
         
+        if not from_supabase:
+            return defaults
+
         try:
             # Try to load from Supabase
             user_email = self._get_effective_user_email()
@@ -1269,10 +1281,14 @@ Try something like:
             
             # Check validation_mode setting. Local launcher runs without Gradio
             # auth, so fall back to the controller's in-memory settings when
-            # user-scoped Supabase settings are unavailable.
+            # user-scoped Supabase settings are unavailable. A run driven by a
+            # settings document never consults Supabase at all.
             try:
                 from supabase_client import load_gradio_settings
-                settings = load_gradio_settings(self._get_effective_user_email())
+                if self._settings_source == 'payload':
+                    settings = self.settings
+                else:
+                    settings = load_gradio_settings(self._get_effective_user_email())
             except Exception as settings_error:
                 print(f"[Settings] Using in-memory settings for validation_mode: {settings_error}", flush=True)
                 settings = self.settings
@@ -4391,9 +4407,14 @@ LegitData will generate realistic, AI-powered data.
             log_progress("SNOWFLAKE DEPLOYMENT COMPLETE")
             log_progress("=" * 60)
             
-            # Check validation_mode setting to decide whether to auto-continue
+            # Check validation_mode setting to decide whether to auto-continue.
+            # A run driven by a settings document never consults Supabase: its
+            # settings dict is complete (validation_mode is 'Off' for headless).
             from supabase_client import load_gradio_settings, get_admin_setting
-            settings = load_gradio_settings(self._get_effective_user_email())
+            if self._settings_source == 'payload':
+                settings = self.settings
+            else:
+                settings = load_gradio_settings(self._get_effective_user_email())
             validation_mode = settings.get('validation_mode', 'Off')
             
             if validation_mode == 'On':
@@ -4739,8 +4760,13 @@ This chat will update when complete."""
             safe_print("="*60, flush=True)
             safe_print("Watch Live Progress tab for real-time updates...\n", flush=True)
             
-            # Load settings
-            settings = load_gradio_settings(self._get_effective_user_email())
+            # Load settings. Tag and prefix below fall back to the SE's stored
+            # values; a run driven by a settings document has them in
+            # self.settings already and must not read Supabase.
+            if self._settings_source == 'payload':
+                settings = self.settings
+            else:
+                settings = load_gradio_settings(self._get_effective_user_email())
             liveboard_name = self.settings.get('liveboard_name', '')
             
             # Default liveboard name to company name (without .com) if blank

demoprep_app/settings/__init__.py

@@ -0,0 +1,6 @@
+"""Settings payload: the SE's DemoPrep settings as one versioned JSON document.
+
+See demoprep_app.settings.payload. The document is produced by the TSE settings
+app, carried by Agent Q on build_demo_from_brief(settings=...), and later may be
+stored one-row-per-SE in Supabase; this package is the only reader either way.
+"""

demoprep_app/settings/payload.py

@@ -0,0 +1,260 @@
+"""The DemoPrep settings payload (schema 1.x) and its one reader.
+
+Contract: docs/demoprep_settings_payload.example.json and
+docs/demoprep_settings_inventory.md. A separate TSE app owns the settings and
+emits this document per SE. Agent Q passes it to build_demo_from_brief as
+`settings`; a later phase stores the same document one-row-per-SE in Supabase.
+Whichever way it arrives, `parse_settings_payload` is the single place its
+rules live, and `apply_build_settings` is the single place it meets the
+controller's settings dict — so the MCP path, the Supabase-document path and
+any future reader agree by construction.
+
+Rules (CLAUDE.md "no silent fallbacks"):
+
+* An unknown top-level key or an unknown key under `build` is refused: a typo
+  must not silently become "use the default".
+* A value outside its allowed set (model, data size, naming style, geo scope,
+  log level) is refused with the allowed values in the message.
+* A key that is absent takes the documented default — the same default the
+  Settings tab shows — which is what "absent" means in the app today.
+* Secrets never appear in the payload and are never read from it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, MutableMapping
+
+from llm_config import UI_MODEL_CHOICES, DEFAULT_LLM_MODEL
+
+# The version this reader understands. Same major = compatible; a payload with a
+# different major is refused outright, a payload with a newer minor is refused
+# too (it may carry a key this server would otherwise drop on the floor).
+SCHEMA_VERSION = "1.0"
+
+# Data Size preset -> (fact rows, dim rows). The ONE copy; the App tab GO path and
+# the MCP build both used to carry their own.
+DATA_SIZE_PRESETS: dict[str, tuple[int, int]] = {
+    "Small": (1000, 50),
+    "Medium": (10000, 500),
+}
+COLUMN_NAMING_STYLES = ("Regular Case", "snake_case", "camelCase", "PascalCase",
+                        "UPPER_CASE", "original")
+GEO_SCOPES = ("USA Only", "International")
+LOG_LEVELS = ("off", "regular", "verbose")
+
+_TOP_LEVEL_KEYS = frozenset({
+    "schema_version", "generated_at", "source", "owner_email",
+    "thoughtspot", "build", "ui_defaults", "admin",
+})
+_BUILD_KEYS = frozenset({
+    "model", "data_size", "fact_table_rows", "dim_table_rows",
+    "column_naming_style", "object_naming_prefix", "liveboard_name", "tag_name",
+    "share_with", "geo_scope", "existing_model_guid",
+})
+_THOUGHTSPOT_KEYS = frozenset({"environment_label", "url"})
+_ADMIN_KEYS = frozenset({"share_with_default", "log_level", "snowflake"})
+_ADMIN_SNOWFLAKE_KEYS = frozenset({"account", "kp_user", "role", "warehouse", "database", "sso_user"})
+
+
+class SettingsPayloadError(ValueError):
+    """The payload cannot be used. The message says exactly which key and why."""
+
+
+@dataclass(frozen=True)
+class BuildSettings:
+    """A parsed, validated payload. Every field has a concrete value."""
+    schema_version: str
+    source: str
+    owner_email: str                 # "" when the payload carries none (the tool arg must then)
+    ts_url: str                      # "" when not given; resolved by the MCP server
+    ts_environment_label: str        # "" when not given; informational unless url is blank
+    model: str
+    data_size: str
+    fact_table_rows: int
+    dim_table_rows: int
+    column_naming_style: str
+    object_naming_prefix: str
+    liveboard_name: str
+    tag_name: str
+    share_with: tuple[str, ...]
+    geo_scope: str
+    existing_model_guid: str
+    admin_share_with_default: tuple[str, ...]
+    admin_log_level: str             # "" when not given
+    admin_snowflake: dict[str, str]  # validated, carried on the run record; NOT applied per build (see docs)
+
+    @property
+    def effective_share_with(self) -> str:
+        """Comma-separated share target the deployer expects: the SE's own list,
+        else the admin default from the payload, else "" (the server decides)."""
+        return ",".join(self.share_with or self.admin_share_with_default)
+
+
+# ----------------------------------------------------------------- helpers
+
+def _section(doc: Mapping[str, Any], name: str, allowed: frozenset[str]) -> dict:
+    raw = doc.get(name)
+    if raw is None:
+        return {}
+    if not isinstance(raw, Mapping):
+        raise SettingsPayloadError(f"{name}: must be an object, got {type(raw).__name__}")
+    unknown = sorted(k for k in raw if k not in allowed and not str(k).startswith("$"))
+    if unknown:
+        raise SettingsPayloadError(f"{name}: unknown key(s) {unknown}; allowed: {sorted(allowed)}")
+    return dict(raw)
+
+
+def _str(section: Mapping[str, Any], key: str, default: str = "", *, where: str) -> str:
+    val = section.get(key, default)
+    if val is None:
+        return default
+    if not isinstance(val, str):
+        raise SettingsPayloadError(f"{where}.{key}: must be a string, got {type(val).__name__}")
+    return val.strip()
+
+
+def _choice(section: Mapping[str, Any], key: str, choices: tuple[str, ...], default: str,
+            *, where: str) -> str:
+    val = _str(section, key, default, where=where) or default
+    if val not in choices:
+        raise SettingsPayloadError(f"{where}.{key}: {val!r} is not one of {list(choices)}")
+    return val
+
+
+def _rows(section: Mapping[str, Any], key: str, *, where: str) -> int | None:
+    val = section.get(key)
+    if val is None or val == "":
+        return None
+    if isinstance(val, bool) or not isinstance(val, int):
+        # bool is an int subclass; refuse it explicitly. Strings are refused too:
+        # the settings app owns typing, a "10000" here is a producer bug.
+        raise SettingsPayloadError(f"{where}.{key}: must be an integer, got {type(val).__name__}")
+    if val <= 0:
+        raise SettingsPayloadError(f"{where}.{key}: must be a positive integer, got {val}")
+    return val
+
+
+def _people(section: Mapping[str, Any], key: str, *, where: str) -> tuple[str, ...]:
+    """A list of user emails / group names, or the comma-separated string the app
+    stores today. Normalised to a tuple of non-blank entries."""
+    val = section.get(key)
+    if val is None:
+        return ()
+    if isinstance(val, str):
+        parts = [p.strip() for p in val.split(",")]
+    elif isinstance(val, (list, tuple)):
+        if not all(isinstance(p, str) for p in val):
+            raise SettingsPayloadError(f"{where}.{key}: every entry must be a string")
+        parts = [p.strip() for p in val]
+    else:
+        raise SettingsPayloadError(f"{where}.{key}: must be a list of strings or a comma-separated string")
+    return tuple(p for p in parts if p)
+
+
+def _check_version(doc: Mapping[str, Any]) -> str:
+    raw = doc.get("schema_version")
+    if not isinstance(raw, str) or not raw.strip():
+        raise SettingsPayloadError("schema_version is required (e.g. \"1.0\")")
+    raw = raw.strip()
+    try:
+        major, minor = (int(p) for p in raw.split("."))
+    except ValueError:
+        raise SettingsPayloadError(f"schema_version: {raw!r} is not MAJOR.MINOR") from None
+    ours_major, ours_minor = (int(p) for p in SCHEMA_VERSION.split("."))
+    if major != ours_major or minor > ours_minor:
+        raise SettingsPayloadError(
+            f"schema_version {raw} is not understood by this server (it reads {SCHEMA_VERSION}); "
+            f"deploy DemoPrep first, or send a {SCHEMA_VERSION} payload")
+    return raw
+
+
+# ------------------------------------------------------------------ parse
+
+def parse_settings_payload(doc: Mapping[str, Any]) -> BuildSettings:
+    """Validate a settings document and return the concrete values a build uses.
+
+    Raises SettingsPayloadError naming the offending key. Never returns a partial
+    result: a payload is either usable in full or refused.
+    """
+    if not isinstance(doc, Mapping):
+        raise SettingsPayloadError(f"settings must be an object, got {type(doc).__name__}")
+    unknown = sorted(k for k in doc if k not in _TOP_LEVEL_KEYS and not str(k).startswith("$"))
+    if unknown:
+        raise SettingsPayloadError(f"unknown top-level key(s) {unknown}; allowed: {sorted(_TOP_LEVEL_KEYS)}")
+
+    version = _check_version(doc)
+    source = _str(doc, "source", where="payload")
+    owner_email = _str(doc, "owner_email", where="payload").lower()
+
+    ts = _section(doc, "thoughtspot", _THOUGHTSPOT_KEYS)
+    build = _section(doc, "build", _BUILD_KEYS)
+    _section(doc, "ui_defaults", frozenset({
+        "use_default_inputs", "vertical", "line", "function", "company_url",
+        "validation_mode", "data_adjuster_url",
+    }))  # accepted for the App tab; a headless build reads none of it
+    admin = _section(doc, "admin", _ADMIN_KEYS)
+    admin_snowflake = _section(admin, "snowflake", _ADMIN_SNOWFLAKE_KEYS)
+    for k, v in admin_snowflake.items():
+        if not isinstance(v, str):
+            raise SettingsPayloadError(f"admin.snowflake.{k}: must be a string")
+
+    model = _choice(build, "model", tuple(UI_MODEL_CHOICES), DEFAULT_LLM_MODEL, where="build")
+    data_size = _choice(build, "data_size", tuple(DATA_SIZE_PRESETS), "Medium", where="build")
+    preset_fact, preset_dim = DATA_SIZE_PRESETS[data_size]
+    fact_rows = _rows(build, "fact_table_rows", where="build")
+    dim_rows = _rows(build, "dim_table_rows", where="build")
+
+    return BuildSettings(
+        schema_version=version,
+        source=source,
+        owner_email=owner_email,
+        ts_url=_str(ts, "url", where="thoughtspot").rstrip("/"),
+        ts_environment_label=_str(ts, "environment_label", where="thoughtspot"),
+        model=model,
+        data_size=data_size,
+        fact_table_rows=fact_rows if fact_rows is not None else preset_fact,
+        dim_table_rows=dim_rows if dim_rows is not None else preset_dim,
+        column_naming_style=_choice(build, "column_naming_style", COLUMN_NAMING_STYLES,
+                                    "Regular Case", where="build"),
+        object_naming_prefix=_str(build, "object_naming_prefix", where="build"),
+        liveboard_name=_str(build, "liveboard_name", where="build"),
+        tag_name=_str(build, "tag_name", where="build"),
+        share_with=_people(build, "share_with", where="build"),
+        geo_scope=_choice(build, "geo_scope", GEO_SCOPES, "USA Only", where="build"),
+        existing_model_guid=_str(build, "existing_model_guid", where="build"),
+        admin_share_with_default=_people(admin, "share_with_default", where="admin"),
+        admin_log_level=(_choice(admin, "log_level", LOG_LEVELS, "regular", where="admin")
+                         if admin.get("log_level") not in (None, "") else ""),
+        admin_snowflake={k: v.strip() for k, v in admin_snowflake.items()},
+    )
+
+
+# ------------------------------------------------------------------ apply
+
+def apply_build_settings(target: MutableMapping[str, Any], s: BuildSettings,
+                         *, share_with_fallback: str = "") -> dict[str, Any]:
+    """Write the payload onto a controller's settings dict, using the exact keys
+    the pipeline reads today (chat_interface / thoughtspot_deployer). Returns
+    what was written, for the run log.
+
+    `share_with_fallback` is the server's own policy (MCP_SHARE_WITH) used only
+    when neither the SE nor the admin default names anyone.
+    """
+    applied = {
+        "model": s.model,
+        "fact_table_size": str(s.fact_table_rows),
+        "dim_table_size": str(s.dim_table_rows),
+        "column_naming_style": s.column_naming_style,
+        "object_naming_prefix": s.object_naming_prefix,
+        "liveboard_name": s.liveboard_name,
+        "tag_name": s.tag_name,
+        "share_with": s.effective_share_with or share_with_fallback,
+        "geo_scope": s.geo_scope,
+        "use_existing_model": bool(s.existing_model_guid),
+        "existing_model_guid": s.existing_model_guid,
+        # Headless builds never pause at checkpoints, whatever the SE's App-tab
+        # preference is (the App tab reads ui_defaults.validation_mode itself).
+        "validation_mode": "Off",
+    }
+    target.update(applied)
+    return applied

docs/agent_q_flags.md

@@ -1,6 +1,6 @@
 # Agent Q → DemoPrep: what to send (flag registry)
 
-*Living document, owned by the release manager. Every change to the `build_demo_from_brief` arguments or the MCP tool list is recorded here first. Last updated 2026-10-21.*
+*Living document, owned by the release manager. Every change to the `build_demo_from_brief` arguments or the MCP tool list is recorded here first. Last updated 2026-10-22.*
 
 **Rule (boone, 2026-10-14 / 10-20):** every feature is **OFF unless Agent Q sends it**. If an argument is omitted, false or blank, the build is exactly what it was before the feature existed.
 
@@ -36,9 +36,12 @@ Status key:
 | `tiers` | `True` | PROD |
 | `pinning` | `False` | PROD |
 | `homepage_screenshot` (also on `build_portal`, `update_portal`) | `""` (none) | BUILT (`feature/home-page-screenshot-wayback`) |
+| `settings` | none: the SE's settings are read from Supabase as before | BUILT (`claude/demo-prep-settings-json-547af4`) |
 
 `homepage_screenshot` is an **input**, not an off-by-default feature: a screenshot of the prospect's home page as an https image URL or a base64 data URI (`data:image/png;base64,...`; png, jpeg or webp, up to 10 MB, at least 320x240; a full-page capture is sliced). The portal's cloned home page (its sign-in page) is built from it instead of the live site. Send it when the site has a bot wall ("Access Denied"). Without it the live site is captured, then, if that is blocked, its latest Internet Archive copy, then the template login. A bad image never fails a build: a warning says why and the next source is used. The result's `home_page.source` says which: `screenshot`, `live`, `wayback (YYYY-MM-DD)` or `template`.
 
+`settings` is the SE's DemoPrep settings as **one JSON object** (schema `1.0`, shape in `docs/demoprep_settings_payload.example.json`), produced by the TSE settings app. Agent Q fetches the SE's document and passes it verbatim. When sent, the build takes model, data size, column naming style, object prefix, liveboard name, tag, share-with and geo scope from it and reads nothing from the SE's Supabase settings. An explicit `owner_email` / `ts_url` on the call still wins over the document; a blank `ts_url` falls back to the document's `thoughtspot.url`, then its `environment_label`. A document with an unknown key, a value outside its allowed set, or a `schema_version` the server does not read is refused before anything is built, and the error names the key. Never put secrets in it. Brief for the app's builder: `docs/settings_app_agent_brief.md`.
+
 ## 3. Feature flags: OFF unless sent
 
 | Flag (what to send) | When omitted | What it turns on | Status | Ref |
@@ -66,6 +69,7 @@ Flag names: boone said "tile=1" / "logo=1". The arguments are named `insight_til
 AgentSpot caches the tool list. **Refresh the tools in Agent Q** after every push that changes this page, or new arguments are invisible and newly required ones fail.
 
 ## Change log
+- 2026-10-22: `settings` (one JSON document per SE from the TSE settings app) on `build_demo_from_brief`; replaces the SE's Supabase settings for that run. Built on `claude/demo-prep-settings-json-547af4` off `b918bd8`.
 - 2026-10-21: `check_homepage(url)` tool: the build's own live-then-Wayback home page capture, run on its own so Agent Q can ask the SE for a screenshot before building (`needs_screenshot`, `message_for_se`).
 - 2026-10-21: `homepage_screenshot` (input on `build_demo_from_brief`, `build_portal`, `update_portal`) and the Internet Archive fallback for a blocked home page; `home_page.source` reports screenshot / live / wayback / template.
 - 2026-10-20: `insight_tile`, `logo_tile` started (ISS-24/25). Jack PR #1 (`salesforce_opportunity_id` + `environment` required) on TEST `2cea704`. Portal editor, chart repair and `deploy_existing_schema` tools on TEST.

docs/demoprep_settings_inventory.md

@@ -0,0 +1,245 @@
+# DemoPrep Settings Inventory and Agent Q Payload (draft 2026-10-13, decisions 2026-10-22)
+
+Companion to `docs/demoprep_settings_payload.example.json`.
+
+**Purpose.** A separate TSE app will own DemoPrep settings. Agent Q will hand a settings
+JSON to DemoPrep's MCP build so DemoPrep no longer reads settings from Supabase per run.
+This doc lists every setting DemoPrep reads today, where it lives, who consumes it, whether
+the MCP path honors it, and whether it belongs in the payload.
+
+**Code audited:** `deploy/mcp` at `4162a45` (the test MCP line; `prod/mcp` differs only in
+`mcp_server.py` plumbing, not in settings). The worktree branch this was written on is
+behind `deploy/mcp` on every settings file, so line numbers below refer to `deploy/mcp`.
+
+**Live data audited:** Supabase `user_settings` on 2026-10-13: 744 rows, 46 users
+(45 SEs + `__admin__`).
+
+---
+
+## 1. The four layers of settings today
+
+| Layer | Where | Read by | Keyed by |
+|---|---|---|---|
+| Per-user settings | Supabase `user_settings` (one row per key, `category='defaults'`) | `load_gradio_settings(email)`, `ChatDemoInterface.load_default_settings()` | SE email |
+| Admin settings | Supabase `user_settings` where `user_email='__admin__'`, `category='admin'` | `get_admin_setting(KEY)`, `inject_admin_settings_to_env()` at boot | system-wide |
+| Environment | HF Space secrets + variables, local `.env` | `os.getenv` | per Space |
+| Per-call arguments | `build_demo_from_brief(...)` / `build_portal(...)` | MCP tool args from Agent Q | per build |
+
+The payload replaces layer 1 and the non-secret half of layer 2. Layer 3 stays on the
+Space. Layer 4 is unchanged.
+
+---
+
+## 2. Per-user settings (Supabase `user_settings`, category `defaults`)
+
+Source of truth for the key list: `SETTINGS_SCHEMA` in `chat_interface.py:145`.
+"MCP honors?" means: does a headless Agent Q build today pick up the SE's saved value.
+
+| Key | Default | Choices | Consumer | MCP honors? | Payload |
+|---|---|---|---|---|---|
+| `default_llm` | `claude-opus-5` | `claude-opus-5`, `claude-sonnet-5` | `controller.settings['model']`; `resolve_model_name()` clamps anything else to default | Yes, if in the allowed list | `build.model` |
+| `default_ts_env` | `secloud - primary` | labels from `TS_ENV_<n>_LABEL` | App tab only: seeds the TS Environment dropdown, which resolves URL + trusted-auth key | No (MCP uses `ts_url` arg or `TS_ENV_URL_DEFAULT`) | `thoughtspot.environment_label` |
+| `liveboard_name` | `""` | free text | deploy stage; blank = `"{Company} - {use case}"` | **No**, never loaded headless | `build.liveboard_name` |
+| `default_data_size` | `Medium` | `Small`, `Medium` | Small = 1,000 fact / 50 dim rows; Medium = 10,000 / 500 | Yes (`mcp_server.py:717`) | `build.data_size` |
+| `fact_table_size`, `dim_table_size` | `1000`, `100` | hidden legacy | overwritten by the data-size preset at GO and in MCP | Superseded | `build.fact_table_rows`, `build.dim_table_rows` (explicit override, optional) |
+| `geo_scope` | `USA Only` | `USA Only`, `International` | **None.** Stored and copied into `controller.settings`, but no pipeline stage reads it | n/a (dead) | `build.geo_scope` (**keep, list it**, decided 10-22) |
+| `tag_name` | `""` | free text | tags model + liveboard after build | Yes | `build.tag_name` |
+| `column_naming_style` | `Regular Case` | `Regular Case`, `snake_case`, `camelCase`, `PascalCase`, `UPPER_CASE`, `original` | `deployer.column_naming_style` (`chat_interface.py:4420`) | **No**, headless builds always get Regular Case | `build.column_naming_style` |
+| `object_naming_prefix` | `""` | free text | DDL + deploy object names | Yes, via the mid-run Supabase re-read at `chat_interface.py:4467` | `build.object_naming_prefix` |
+| `share_with` | `""` | comma-separated users / groups | share model + liveboard; falls back to admin `SHARE_WITH` | **No**, env `MCP_SHARE_WITH` overrides (default `mike.boone@thoughtspot.com`) | `build.share_with` (list) |
+| `validation_mode` | `Off` | `On`, `Off` | App tab checkpoint pauses only | No, headless is always auto-run | `ui_defaults.validation_mode` |
+| `use_default_inputs` | `false` | bool | App tab pre-fill switch | No | `ui_defaults.use_default_inputs` |
+| `default_vertical`, `default_line`, `default_function`, `default_company_url` | `""` | matrix values / URL | App tab pre-fill | No (Agent Q passes `use_case` + `company_url` per call) | `ui_defaults.*` |
+| `default_use_case` | `Sales Analytics` | hidden legacy | seeds `controller.settings['use_case']`, overridden by the per-call arg | Superseded | not needed |
+| `use_existing_model`, `existing_model_guid` | `false`, `""` | hidden legacy | skips model creation, builds a liveboard on an existing model (`chat_interface.py:4247`) | No, never loaded headless | `build.existing_model_guid` (blank = build a model) |
+| `data_adjuster_url` | `""` | URL | Settings tab shortcut into Data Adjuster | No | `ui_defaults.data_adjuster_url` |
+| `temperature`, `max_tokens`, `batch_size`, `thread_count` | `0.3`, `4000`, `5000`, `4` | "Advanced AI Settings (Admin)" accordion | **None.** Stored, never read by the pipeline | n/a (dead) | **drop** (decided 10-22) |
+| `snowflake_account`, `snowflake_user`, `snowflake_role`, `default_warehouse`, `default_database`, `default_schema` | `""`, `""`, `ACCOUNTADMIN`, `COMPUTE_WH`, `DEMO_DB`, `PUBLIC` | "Database Connections (Admin)" accordion | **None.** Pipeline uses the admin `SNOWFLAKE_*` keys | n/a (dead) | **drop** (decided 10-22) |
+| `thoughtspot_username` | `""` | text | **None.** The deployer authenticates as the owner email | n/a (dead) | **drop** (decided 10-22); owner is `owner_email` |
+
+### What the live data says
+
+- Every SE is on the defaults: 44/44 `Medium`, 45/45 `USA Only`, 45/45 `Regular Case`, 44/45 `Off`.
+- `default_llm`: 20 on `claude-sonnet-4-6`, 13 on `claude-opus-5`, **12 still on `gpt-5.5`**. All non-allowed values silently resolve to `claude-opus-5` at run time.
+- `default_ts_env`: 42 `secloud - primary`, 2 `sebe - se`.
+- `share_with` is set for only 4 users; everyone else inherits admin `SHARE_WITH`.
+- 4 old accounts carry pre-redesign keys with a null category (`company_size`,
+  `default_data_volume`, `liveboard_method`, `naming_prefix`, per-user `snowflake_*`). All dead.
+
+### What `geo_scope` was meant to do, and why it does nothing
+
+The "Geographic Scope" dropdown (right panel and Settings tab) offers `USA Only` or
+`International`, with the hint "US states/cities/USD vs global". It was meant to steer the
+generated data. It never reached the current generator:
+
+- The current pipeline (`build_demo()` in `demoprep_app/pipeline/build_demo.py`) and every
+  module under `demoprep_app/dataset` contain no reference to the setting. Region values are
+  hard-coded per vertical in `template_generator.py:928` and already mix US and
+  international names (`North America`, `EMEA`, `APAC`, `Latin America`).
+- The only "USA Only" guidance in the codebase is a hard-coded prompt block in the legacy
+  `demo_prep.py` interface (`create_demo_prep_interface`, around line 1677). It is fixed text,
+  not driven by the dropdown, and that interface is not the App-tab or MCP path.
+- `git log -S geo_scope` over the generator modules is empty: no consumer was removed. It was
+  never wired.
+
+So every build today ignores the dropdown, and 45 of 45 SEs have it on `USA Only` while
+the generated data is already mixed-geography. **Decision 10-22: keep it and list it** in the
+payload (`build.geo_scope`). Wiring it into the generator is a separate generator feature.
+
+### Keys that matter for a headless build
+
+Only these per-user keys change what an Agent Q build produces, and today the MCP path
+honors just three of them: **`default_llm`, `default_data_size`, `tag_name`,
+`object_naming_prefix`** are honored; **`column_naming_style`, `liveboard_name`,
+`share_with`** are ignored. The payload fixes that gap for free.
+
+---
+
+## 3. Admin settings (Supabase `__admin__`, category `admin`)
+
+Registry: `ADMIN_SETTINGS_KEYS` in `supabase_client.py:618`. Loaded once at boot by
+`inject_admin_settings_to_env()` and read on demand via `get_admin_setting()`.
+
+| Key | Live value | Secret? | Consumer | Payload |
+|---|---|---|---|---|
+| `SNOWFLAKE_ACCOUNT` | `THOUGHTSPOT_PARTNER` | no | `snowflake_auth.py:157`, deployer connection create | `admin.snowflake.account` |
+| `SNOWFLAKE_KP_USER` | `SE_DEMO_KP` | no | key-pair user | `admin.snowflake.kp_user` |
+| `SNOWFLAKE_KP_PK` | set | **yes** | `snowflake_auth.py:112` | **never**; leave blank / omitted |
+| `SNOWFLAKE_KP_PASSPHRASE` | set | **yes** | `snowflake_auth.py:121` | **never**; leave blank / omitted |
+| `SNOWFLAKE_ROLE` | `SE_ROLE` | no | connection role | `admin.snowflake.role` |
+| `SNOWFLAKE_WAREHOUSE` | `SE_DEMO_WH` | no | connection warehouse | `admin.snowflake.warehouse` |
+| `SNOWFLAKE_DATABASE` | `DEMOBUILD` | no | base name; `get_demo_database()` rotates to `DEMOBUILD_YYYY_MM` | `admin.snowflake.database` |
+| `SNOWFLAKE_SSO_USER` | `mike.boone@thoughtspot.com` | no | Snowflake browser auth (Data Adjuster) | `admin.snowflake.sso_user` |
+| `SNOWFLAKE_SCHEMA` | not set (falls to `PUBLIC`) | no | read via `get_admin_setting` but not in the registry | omit |
+| `SHARE_WITH` | `mike.boone@thoughtspot.com` | no | fallback share target when the user's `share_with` is blank | `admin.share_with_default` |
+| `LOG_LEVEL` | not set (falls to `regular`) | no | `session_logger.py:266`: `off` / `regular` / `verbose` | `admin.log_level` |
+| `THOUGHTSPOT_URL` | not set | no | **Dead.** Replaced by the `TS_ENV_<n>` table; hidden in the Admin tab | omit |
+| `OPENAI_API_KEY`, `GOOGLE_API_KEY` | not set | yes | **Dead in Supabase.** Explicitly skipped by `inject_admin_settings_to_env()`; env only | omit |
+
+**Decided 10-22:** the non-secret Snowflake block travels in the payload as
+`admin.snowflake`. The Snowflake key and passphrase are never in the payload; where they are
+kept is out of scope for this doc and does not block the settings-app move. (For the record:
+today the code reads them through `get_admin_setting()`, i.e. the Supabase admin row.)
+
+---
+
+## 4. Environment (HF Space secrets and variables; stays server-side)
+
+Nothing in this section belongs in the payload. Listed so the settings app knows what it
+does **not** own.
+
+| Group | Variables | Default |
+|---|---|---|
+| Bootstrap | `SUPABASE_URL`, `SUPABASE_ANON_KEY` | required until the payload replaces Supabase |
+| LLM keys | `ANTHROPIC_API_KEY` (required), `OPENAI_API_KEY`, `GOOGLE_API_KEY` | env only |
+| ThoughtSpot env table | `TS_ENV_<n>_LABEL`, `TS_ENV_<n>_URL`, `TS_ENV_<n>_KEY_VAR` (value or `ENV:<NAME>` indirection) | 1 = `secloud - primary`, 2 = `sebe - se`, 3 = `techpartners` |
+| ThoughtSpot defaults | `TS_ENV_URL_DEFAULT`, `TS_USER_DEFAULT`, `TS_AUTH_KEY` (direct key override) | per Space |
+| MCP | `MCP_ACCESS_TOKEN`, `MCP_TRANSPORT`, `MCP_HTTP_PORT`, `MCP_MAX_CONCURRENT_BUILDS`, `MCP_SHARE_WITH`, `MCP_HIT_LOG`, `MCP_USE_DIRECT_API` | `http`, `7860`, `3`, `mike.boone@thoughtspot.com`, unset, `true` |
+| Feature flags | `MUZE_ENGINE_MAIN_TABS`, `USE_ADVANCED_TML` | unset = `true`, `true` |
+| ThoughtSpot retry tuning | `TS_AUTH_MAX_ATTEMPTS`, `TS_AUTH_RETRY_WAIT_SECONDS`, `TS_MODEL_READY_TIMEOUT_SECONDS`, `TS_MODEL_READY_POLL_INTERVAL_SECONDS`, `TS_CONNECTION_CREATE_MAX_ATTEMPTS`, `TS_CONNECTION_CREATE_RETRY_WAIT_SECONDS`, `TS_TML_ASYNC_POLL_INTERVAL_SECONDS`, `TS_TML_ASYNC_TIMEOUT_SECONDS` | `3`, `5`, `300`, `30`, `3`, `20`, `5`, `900` |
+| Slack | `SLACK_BOT_TOKEN`, `SLACK_DEPLOYMENT_CHANNEL_ID` (or `SLACK_CHANNEL_ID`), `SLACK_NOTIFICATIONS_ENABLED` | `true` |
+| Portal / HF | `HF_TOKEN`, `SPACE_ID`, `SPACE_HOST`, `GIT_COMMIT` | set by HF |
+| App | `APP_ENV`, `DEMOPREP_NO_AUTH`, `DEMOPREP_DEV_USER_EMAIL`, `DEMOPREP_APP_URL` / `PUBLIC_APP_URL`, `DEBUG`, `PORT` | `production`, local dev only |
+
+Two stale spots found on the way: the README documents `MCP_OWNER_EMAIL` and
+`MCP_TS_ENV_LABEL`, but the code reads `TS_USER_DEFAULT` and `TS_ENV_URL_DEFAULT`; and
+`validate_required_settings()` still demands `OPENAI_API_KEY` although the pipeline runs on
+Anthropic.
+
+---
+
+## 5. Per-call arguments Agent Q already passes (unchanged)
+
+`build_demo_from_brief(brief, company_name, use_case, company_url, ts_url, owner_email,
+with_portal)` and `build_portal(...)` with its ~40 styling arguments. These are per-demo
+inputs, not settings, and stay as they are. The payload adds one more argument.
+
+---
+
+## 6. Implementation (built 2026-10-22, branch `claude/demo-prep-settings-json-547af4` off `b918bd8` = test and prod tip; not pushed)
+
+1. **New tool argument.** `build_demo_from_brief(..., settings: dict | None = None)`,
+   keyword-only, optional. Agent Q fetches the SE's document from the settings app and
+   passes it through verbatim. Without it the build behaves exactly as before.
+2. **One reader.** `demoprep_app/settings/payload.py`: `parse_settings_payload()` validates
+   the document (schema major 1, allowed values, no unknown keys, no partial results) and
+   `apply_build_settings()` writes it onto the controller's settings dict under the exact
+   keys the pipeline reads today. The data-size preset table lives there now.
+3. **Precedence.** Explicit `owner_email` / `ts_url` on the call win; otherwise they come
+   from the document (`thoughtspot.url`, then `thoughtspot.environment_label` resolved
+   through the `TS_ENV_<n>` table by `_ts_url_for_label()`). Everything under `build`
+   comes from the document. A bad document is refused before the ThoughtSpot target is
+   resolved or a build slot is taken; the error names the key.
+4. **Supabase is not consulted for a document-driven run.** The controller is built with
+   `settings_from_supabase=False` (new keyword on `ChatDemoInterface`), and the three
+   mid-run re-reads of `load_gradio_settings()` in chat_interface (chat path, Snowflake
+   stage, ThoughtSpot stage) are guarded by `_settings_source == 'payload'`.
+5. **Provenance.** The run record carries `settings_source` (`payload` / `supabase`) and
+   `settings_schema_version`; the server log line shows every applied value.
+6. **Tests.** `tests/test_settings_payload.py` (30, pure) and
+   `tests/test_mcp_settings_document.py` (12: tool schema, refusals, precedence, label
+   resolution, controller and guards). One existing fixture stub updated to the new loader
+   signature (`tests/test_custom_mcp_demo_pack.py`).
+
+Mapping from document to what the pipeline reads:
+
+| Document field | Applied as |
+|---|---|
+| `owner_email` | `_resolve_owner()` unless the call passes `owner_email` |
+| `thoughtspot.url`, then `thoughtspot.environment_label` | `_resolve_ts_target()` unless the call passes `ts_url` |
+| `build.model` | `controller.settings['model']` |
+| `build.data_size` / `fact_table_rows` / `dim_table_rows` | `fact_table_size`, `dim_table_size` (strings, as the App tab stores them) |
+| `build.column_naming_style` | `deployer.column_naming_style` via `controller.settings` |
+| `build.object_naming_prefix`, `liveboard_name`, `tag_name` | same keys on `controller.settings` |
+| `build.share_with`, else `admin.share_with_default`, else env `MCP_SHARE_WITH` | `controller.settings['share_with']` (comma-joined) |
+| `build.existing_model_guid` | `use_existing_model = bool(guid)`, `existing_model_guid` |
+| `build.geo_scope` | `controller.settings['geo_scope']` (no consumer yet, listed per boone) |
+| `ui_defaults.*` | validated, ignored by a headless build; `validation_mode` is forced `Off` |
+| `admin.log_level`, `admin.snowflake.*` | validated and recorded on the run; **not applied per build** (see phase 2) |
+
+`with_portal` was dropped from the document: it is a per-demo choice Agent Q already
+passes on the call, not a persistent setting.
+
+### Phase 2 scope: the document in Supabase (not built)
+
+Boone 10-22: "pretty soon we may just do it in the database". Same document, stored, one
+row per SE. DemoPrep reads it when a build arrives without `settings`.
+
+```sql
+create table if not exists demoprep_settings (
+  owner_email    text primary key,
+  schema_version text not null,
+  document       jsonb not null,
+  updated_at     timestamptz not null default now(),
+  updated_by     text not null
+);
+```
+
+Code, when the time comes (small, because the parser already exists):
+
+1. `supabase_client.load_settings_document(owner_email) -> dict | None` using the cached
+   `_reader()`; raises when Supabase is unconfigured (a read that silently returns nothing
+   would be reported as "no settings").
+2. In `build_demo_from_brief`: `doc = settings if settings is not None else
+   load_settings_document(owner_email)`; then the existing parse-and-apply path. Order:
+   call argument, then the Supabase row, then (until cutover) today's per-key behaviour.
+   After cutover the per-key path is deleted and "no row" fails loud.
+3. `admin.*` moves with it: `inject_admin_settings_to_env()` reads the admin document at
+   boot instead of the `__admin__` per-key rows. Per-build application of
+   `admin.snowflake` is deliberately not done: `SNOWFLAKE_*` are process-wide environment
+   values and concurrent builds share the process.
+4. The settings app writes with a service-role key; DemoPrep reads with the anon key it
+   already holds. The Gradio Settings tab either becomes read-only or writes the same row.
+
+## 7. Decisions (boone, 2026-10-22)
+
+| # | Question | Decision |
+|---|---|---|
+| 1 | Does the App tab keep reading Supabase? | Settings stay in Supabase for the App tab (read as boone's "the settings are in Supabase"; confirm if that was not the intent) |
+| 2 | Non-secret Snowflake block: payload or Space secrets? | Payload (`admin.snowflake`). Key and passphrase never in the payload; their storage is out of scope here |
+| 3 | `geo_scope`: wire or drop? | **Keep, list it.** Stays in the payload as `build.geo_scope`; generator wiring is separate work |
+| 4 | `share_with` list or string? | No preference; keeping the list as drafted |
+| 5 | Drop the dead per-user fields? | **Yes.** `temperature`, `max_tokens`, `batch_size`, `thread_count`, per-user `snowflake_*`, `thoughtspot_username` are out of the new app; the parser refuses them as unknown keys |
+| 6 | Schema version check? | Needed explaining. Plain version: the JSON carries `schema_version` (already in the example). When the settings app later adds a field, a DemoPrep Space that predates it compares the number and says "payload is newer than I understand" instead of silently ignoring the field. One `if` on the DemoPrep side; recommend yes |
+| 7 | `with_portal` in the document? | **No** (10-22, DemoPrep side): it is a per-demo call argument, not a setting; removed from the example |
+| 8 | Deliverables for the other side | `docs/settings_app_agent_brief.md` (paste to the agent building the settings app); DemoPrep reader built, see section 6 |

docs/demoprep_settings_payload.example.json

@@ -0,0 +1,49 @@
+{
+  "$comment": "DemoPrep settings document, schema 1.0 (2026-10-22). One per SE, produced by the TSE settings app, handed to DemoPrep by Agent Q as build_demo_from_brief(settings=...), later stored one row per SE in Supabase. Secrets never travel here (Snowflake key/passphrase, ThoughtSpot trusted-auth keys, LLM keys, MCP bearer, Supabase creds). Field rules: docs/demoprep_settings_inventory.md; reader: demoprep_app/settings/payload.py",
+  "schema_version": "1.0",
+  "generated_at": "2026-10-13T00:00:00Z",
+  "source": "tse-settings-app",
+  "owner_email": "se.name@thoughtspot.com",
+  "thoughtspot": {
+    "environment_label": "secloud - primary",
+    "url": "https://se-thoughtspot-cloud.thoughtspot.cloud"
+  },
+  "build": {
+    "model": "claude-opus-5",
+    "data_size": "Medium",
+    "fact_table_rows": 10000,
+    "dim_table_rows": 500,
+    "column_naming_style": "Regular Case",
+    "object_naming_prefix": "",
+    "liveboard_name": "",
+    "tag_name": "",
+    "share_with": [
+      "mike.boone@thoughtspot.com"
+    ],
+    "geo_scope": "USA Only",
+    "existing_model_guid": ""
+  },
+  "ui_defaults": {
+    "use_default_inputs": false,
+    "vertical": "",
+    "line": "",
+    "function": "",
+    "company_url": "",
+    "validation_mode": "Off",
+    "data_adjuster_url": ""
+  },
+  "admin": {
+    "share_with_default": [
+      "mike.boone@thoughtspot.com"
+    ],
+    "log_level": "regular",
+    "snowflake": {
+      "account": "THOUGHTSPOT_PARTNER",
+      "kp_user": "SE_DEMO_KP",
+      "role": "SE_ROLE",
+      "warehouse": "SE_DEMO_WH",
+      "database": "DEMOBUILD",
+      "sso_user": "mike.boone@thoughtspot.com"
+    }
+  }
+}

docs/settings_app_agent_brief.md

@@ -0,0 +1,136 @@
+# Brief: build the TSE "DemoPrep Settings" app
+
+*Paste this whole file to the agent building the settings app. Written 2026-10-22 from the DemoPrep side; DemoPrep's reader for the document described here is already implemented (`demoprep_app/settings/payload.py`).*
+
+## What you are building
+
+A small TSE-side app where a Sales Engineer edits their DemoPrep settings. Its output is **one JSON document per SE** in the shape below (schema `1.0`). DemoPrep no longer looks an SE's settings up in Supabase when it receives this document.
+
+Two delivery phases. Build phase 1 now; design for phase 2.
+
+1. **Phase 1, file.** The app can hand out the SE's current document on request. Agent Q (the AgentSpot agent that calls DemoPrep's MCP server) fetches it and passes it verbatim as the `settings` argument of DemoPrep's `build_demo_from_brief` tool. Expose it as an authenticated HTTPS endpoint, `GET /demoprep/settings/{owner_email}` returning `application/json`, plus a "download JSON" button for a human. Bearer-protect the endpoint; Agent Q will hold the token.
+2. **Phase 2, Supabase.** The app writes the same document to DemoPrep's Supabase project, one row per SE, instead of (or as well as) serving it. DemoPrep will read that row when a build arrives without a `settings` argument. Table and reader are specified at the end. Do not write to the existing `user_settings` table; that is the legacy per-key store the Gradio app still uses.
+
+## The document
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-10-13T00:00:00Z",
+  "source": "tse-settings-app",
+  "owner_email": "se.name@thoughtspot.com",
+  "thoughtspot": {
+    "environment_label": "secloud - primary",
+    "url": "https://se-thoughtspot-cloud.thoughtspot.cloud"
+  },
+  "build": {
+    "model": "claude-opus-5",
+    "data_size": "Medium",
+    "fact_table_rows": 10000,
+    "dim_table_rows": 500,
+    "column_naming_style": "Regular Case",
+    "object_naming_prefix": "",
+    "liveboard_name": "",
+    "tag_name": "",
+    "share_with": ["mike.boone@thoughtspot.com"],
+    "geo_scope": "USA Only",
+    "existing_model_guid": ""
+  },
+  "ui_defaults": {
+    "use_default_inputs": false,
+    "vertical": "",
+    "line": "",
+    "function": "",
+    "company_url": "",
+    "validation_mode": "Off",
+    "data_adjuster_url": ""
+  },
+  "admin": {
+    "share_with_default": ["mike.boone@thoughtspot.com"],
+    "log_level": "regular",
+    "snowflake": {
+      "account": "THOUGHTSPOT_PARTNER",
+      "kp_user": "SE_DEMO_KP",
+      "role": "SE_ROLE",
+      "warehouse": "SE_DEMO_WH",
+      "database": "DEMOBUILD",
+      "sso_user": "mike.boone@thoughtspot.com"
+    }
+  }
+}
+```
+
+### Field rules (validate these in the app; DemoPrep refuses anything else)
+
+| Field | Type | Allowed / default | Notes |
+|---|---|---|---|
+| `schema_version` | string | `"1.0"` | Required. DemoPrep refuses a version it does not read. |
+| `generated_at` | ISO-8601 string | | When the document was produced. |
+| `source` | string | `"tse-settings-app"` | Recorded on the run. |
+| `owner_email` | string | the SE's ThoughtSpot login email | The build authenticates as this user and they own the created objects. Lower-cased. |
+| `thoughtspot.environment_label` | string | one of DemoPrep's environment labels: `secloud - primary`, `sebe - se`, `techpartners` | Shown to the SE as the "TS Environment" choice. |
+| `thoughtspot.url` | string | the URL for that label (see table below) | **Send both.** DemoPrep uses `url` first and only falls back to the label. |
+| `build.model` | string | `claude-opus-5` (default), `claude-sonnet-5` | Anything else is refused. |
+| `build.data_size` | string | `Small` (1,000 fact / 50 dim rows), `Medium` (10,000 / 500, default) | |
+| `build.fact_table_rows`, `build.dim_table_rows` | integer > 0 | derived from `data_size` when absent | Send them only when the SE overrides the preset. Integers, not strings. |
+| `build.column_naming_style` | string | `Regular Case` (default), `snake_case`, `camelCase`, `PascalCase`, `UPPER_CASE`, `original` | |
+| `build.object_naming_prefix` | string | `""` | Prefix on Snowflake schema and ThoughtSpot object names. |
+| `build.liveboard_name` | string | `""` | Blank = DemoPrep derives it from the company. |
+| `build.tag_name` | string | `""` | ThoughtSpot tag applied to the model and liveboard. |
+| `build.share_with` | list of strings | `[]` | ThoughtSpot users or groups the model and liveboard are shared with. A comma-separated string is also accepted. |
+| `build.geo_scope` | string | `USA Only` (default), `International` | Listed by request; the generator does not act on it yet. |
+| `build.existing_model_guid` | string | `""` | Non-blank = build the liveboard on that existing model instead of creating one. |
+| `ui_defaults.*` | | as shown | Gradio App-tab prefill only; a headless build ignores it. `validation_mode` is `On` or `Off`. |
+| `admin.share_with_default` | list of strings | | Fallback share target when `build.share_with` is empty. Admin-level, same for every SE. |
+| `admin.log_level` | string | `off`, `regular`, `verbose` | |
+| `admin.snowflake.*` | strings | as shown | Non-secret connection identity. DemoPrep records it; it is still applied from the server's own configuration in v1. |
+
+Environment labels and URLs today:
+
+| Label | URL |
+|---|---|
+| `secloud - primary` | `https://se-thoughtspot-cloud.thoughtspot.cloud` |
+| `sebe - se` | `https://sebe.thoughtspotstaging.cloud` |
+| `techpartners` | `https://techpartners.thoughtspot.cloud` |
+
+### Rules that are not negotiable
+
+- **No secrets, ever.** Not the Snowflake private key or passphrase, not ThoughtSpot trusted-auth keys, not LLM keys, not the MCP bearer, not Supabase credentials. The document passes through an LLM as tokens.
+- **Unknown keys are refused**, at the top level and inside `build`, `thoughtspot`, `admin`, `ui_defaults`. A typo must not silently become "default". Keys starting with `$` are comments and ignored.
+- **A value outside its allowed set is refused** with the allowed values in the message. Mirror the same lists in the app's dropdowns so the SE cannot produce a document DemoPrep rejects.
+- **Absent optional keys take the defaults above.** Emit the full document anyway; it makes the record self-explaining.
+- Bump `schema_version` only when a key is added, renamed or its rules change. DemoPrep ships its reader first; a document newer than the server is refused, not partially applied.
+
+## How Agent Q uses it
+
+Agent Q already calls `build_demo_from_brief(brief, company_name, salesforce_opportunity_id, environment, owner_email, ts_url, ...)`. The only change: it fetches the SE's document from your endpoint and adds `settings=<document>`. Precedence inside DemoPrep: an explicit `owner_email` or `ts_url` on the call wins over the document; everything under `build` comes from the document; Supabase is not consulted for that run.
+
+## Phase 2: the Supabase row
+
+Same document, stored. DemoPrep's Supabase project, new table:
+
+```sql
+create table if not exists demoprep_settings (
+  owner_email    text primary key,
+  schema_version text not null,
+  document       jsonb not null,
+  updated_at     timestamptz not null default now(),
+  updated_by     text not null
+);
+```
+
+- One row per SE; `owner_email` lower-cased; `document` is the full JSON above; `schema_version` duplicated out of the document for cheap filtering.
+- The app upserts on save. Writes use a service-role key held by the app, never the anon key.
+- DemoPrep side (not yours): `supabase_client.load_settings_document(owner_email)` reads the row through the same parser the `settings` argument uses, so the two phases behave identically. A build with no `settings` argument reads the row; no row means the legacy per-key behaviour until the migration is declared done.
+
+## Reference in the DemoPrep repo
+
+- `docs/demoprep_settings_payload.example.json` is the canonical example (keep it in sync with what you emit).
+- `docs/demoprep_settings_inventory.md` is the full inventory of every setting, where it lives today and what consumes it.
+- `demoprep_app/settings/payload.py` is the reader; `tests/test_settings_payload.py` pins its rules. If the app and the reader disagree, the reader is the contract.
+
+## Questions to settle with boone before you finish
+
+1. Who may edit `admin.*`: every SE's document carries it, but only an admin should change it. Suggest the app stores admin values once and stamps them into every document on export.
+2. Authentication for the SE: SSO identity must equal `owner_email`; do not let an SE type an arbitrary owner.
+3. Endpoint token for Agent Q: who issues and rotates it.

mcp_server.py

@@ -111,6 +111,12 @@ from llm_config import BLUEPRINT_LLM_MODEL, DEFAULT_LLM_MODEL
 # Which Space this process runs in and which commit it runs — stamped on every
 # run record and reported by ping/config_check (resolved once, never raises).
 from demoprep_app.deployment_identity import deployment_identity
+# The SE's settings as ONE document (schema 1.x), produced by the TSE settings app
+# and carried by Agent Q (boone 2026-10-22). Parser and apply step live in one
+# place so every reader agrees; see docs/demoprep_settings_inventory.md.
+from demoprep_app.settings.payload import (
+    BuildSettings, SettingsPayloadError, apply_build_settings, parse_settings_payload,
+)
 # The yes/no reader the portal answers already use (blank = not stated), so the
 # custom_mcp_demo flag follows the same rule. Imported here so a break fails at boot.
 from demoprep_app.portal.builder import _as_bool as _read_yes_no
@@ -216,6 +222,27 @@ def _resolve_ts_target(ts_url: str) -> tuple[str, str]:
     )
 
 
+def _ts_url_for_label(label: str) -> str:
+    """URL of the TS_ENV_<n> entry whose LABEL matches (case-insensitive).
+
+    The settings document names the SE's environment the way the App tab's
+    dropdown does ("secloud - primary"). Labels are cosmetic on the Space (a
+    Space may set URL + KEY_VAR without one, in which case the label is the
+    host), so a document should carry thoughtspot.url as well; the label is
+    the fallback. Fails loud listing the labels this server knows.
+    """
+    wanted = (label or "").strip().lower()
+    table = _ts_env_table()
+    for env_label, url, _key in table:
+        if env_label.strip().lower() == wanted and url:
+            return url
+    known = ", ".join(repr(l) for l, _, _ in table) or "(none)"
+    raise RuntimeError(
+        f"No TS_ENV entry is labelled {label!r} on this server. Known labels: {known}. "
+        f"Send thoughtspot.url in the settings document, or pass ts_url."
+    )
+
+
 # (connect, read) seconds — 10 s worst case. Short on purpose: FastMCP runs this
 # sync tool on the server's event loop, so the wait stalls status() polls. A
 # precheck that gets no answer in time lets the build go ahead (the deployer's
@@ -759,7 +786,8 @@ def _run_build(run_id: str, brief: str, company_name: str, use_case: str, compan
                brand: dict | None = None,
                custom_mcp_demo: bool | str = False,
                header_tiles: dict | None = None,
-               *, schema_style: str, homepage_screenshot: str = "") -> dict:
+               *, schema_style: str, homepage_screenshot: str = "",
+               build_settings: BuildSettings | None = None) -> dict:
     """Drive the controller headlessly (runs in a BACKGROUND THREAD; the caller has
     already registered the build in _active_builds and holds a _build_sem slot).
     With `existing_schema` + `existing_ddl` (deploy_existing_schema) the dataset,
@@ -954,36 +982,53 @@ def _run_build(run_id: str, brief: str, company_name: str, use_case: str, compan
     try:
         # (i) controller — acting user = the per-build owner (per-instance; no
         # process-global write, so concurrent builds never race on the owner).
-        controller = ChatDemoInterface(user_email=owner)
+        # With a settings document the controller skips its Supabase settings
+        # read entirely: the document is this run's whole settings source.
+        controller = ChatDemoInterface(user_email=owner,
+                                       settings_from_supabase=build_settings is None)
 
-        # (ii) settings: model + fixed TS env (exact key names per the wiring trace)
-        controller.settings["model"] = controller.settings.get("model") or DEFAULT_LLM_MODEL
+        # (ii) ThoughtSpot target: fixed per build, never read from a settings store.
         controller.settings["thoughtspot_url"] = ts_target_url
         controller.settings["thoughtspot_trusted_auth_key"] = ts_auth_key
-        # Always share the created model + liveboard with the operator, so every demo is
-        # visible no matter who ran it. The OWNER is unchanged — whoever was passed as
-        # owner_email (the build authenticates AS that user, so they own the objects);
-        # this just adds the operator as a viewer. Override target via MCP_SHARE_WITH.
-        controller.settings["share_with"] = os.getenv("MCP_SHARE_WITH", "mike.boone@thoughtspot.com")
-
-        # (ii-b) Data Size — resolve exactly like the App tab GO path does
-        # (chat_interface defined_go, _size_map): default_data_size drives
-        # fact/dim row counts. load_default_settings() only reads the LEGACY
-        # fact_table_size field, which is stale ('1000') for users who set
-        # Data Size after the Settings Redesign — that silently gave every MCP
-        # build 500-row fact tables while App builds got 3,333 (found 2026-08-25:
-        # all 3 replay boards graded 42-62/100 with "thin data" the top defect).
-        _SIZE_MAP = {
-            "Small":  ("1000",  "50"),
-            "Medium": ("10000", "500"),
-        }
-        _data_size = str(
-            load_gradio_settings(owner).get("default_data_size", "")
-        ).strip() or "Medium"
-        _ft, _dt = _SIZE_MAP.get(_data_size, _SIZE_MAP["Medium"])
-        controller.settings["fact_table_size"] = _ft
-        controller.settings["dim_table_size"] = _dt
-        _log_hit(f"data size: {_data_size} -> fact_rows={_ft} dim_rows={_dt} (owner setting)")
+
+        if build_settings is not None:
+            # (ii-a) Settings document (boone 2026-10-22): model, data size, naming
+            # style, object prefix, liveboard name, tag and share-with all come
+            # from the document. The per-key Supabase lookups in the else branch
+            # are not consulted at all for this run.
+            applied = apply_build_settings(
+                controller.settings, build_settings,
+                share_with_fallback=os.getenv("MCP_SHARE_WITH", "mike.boone@thoughtspot.com"))
+            _log_hit(f"settings: document schema {build_settings.schema_version} "
+                     f"source={build_settings.source!r} -> {applied}")
+        else:
+            # (ii-b) Legacy: per-key Supabase settings (load_default_settings ran in
+            # the constructor) plus the server's own share-with and data-size rules.
+            controller.settings["model"] = controller.settings.get("model") or DEFAULT_LLM_MODEL
+            # Always share the created model + liveboard with the operator, so every demo is
+            # visible no matter who ran it. The OWNER is unchanged — whoever was passed as
+            # owner_email (the build authenticates AS that user, so they own the objects);
+            # this just adds the operator as a viewer. Override target via MCP_SHARE_WITH.
+            controller.settings["share_with"] = os.getenv("MCP_SHARE_WITH", "mike.boone@thoughtspot.com")
+
+            # (ii-b) Data Size — resolve exactly like the App tab GO path does
+            # (chat_interface defined_go, _size_map): default_data_size drives
+            # fact/dim row counts. load_default_settings() only reads the LEGACY
+            # fact_table_size field, which is stale ('1000') for users who set
+            # Data Size after the Settings Redesign — that silently gave every MCP
+            # build 500-row fact tables while App builds got 3,333 (found 2026-08-25:
+            # all 3 replay boards graded 42-62/100 with "thin data" the top defect).
+            _SIZE_MAP = {
+                "Small":  ("1000",  "50"),
+                "Medium": ("10000", "500"),
+            }
+            _data_size = str(
+                load_gradio_settings(owner).get("default_data_size", "")
+            ).strip() or "Medium"
+            _ft, _dt = _SIZE_MAP.get(_data_size, _SIZE_MAP["Medium"])
+            controller.settings["fact_table_size"] = _ft
+            controller.settings["dim_table_size"] = _dt
+            _log_hit(f"data size: {_data_size} -> fact_rows={_ft} dim_rows={_dt} (owner setting)")
 
         # vertical / function / use_case_config exactly as the runner does
         controller.vertical, controller.function = parse_use_case(use_case or "")
@@ -1025,6 +1070,9 @@ def _run_build(run_id: str, brief: str, company_name: str, use_case: str, compan
             'schema_style': schema_style,
             # Resolved yes/no (the raw value is on the intake row).
             'custom_mcp_demo': custom_mcp_on,
+            # Where this run's settings came from: the Agent Q document or Supabase.
+            'settings_source': 'payload' if build_settings is not None else 'supabase',
+            'settings_schema_version': build_settings.schema_version if build_settings else '',
         }
         # One fact ('simple') or 1-3 ('complex'): read by run_ddl_creation ->
         # build_demo -> author_blueprint (ISS-16).
@@ -1425,6 +1473,9 @@ def build_demo_from_brief(
     # An INPUT, not a feature flag: the SE's picture of the prospect's home
     # page, used for the cloned login before the live site (2026-10-21).
     homepage_screenshot: str = "",
+    # The SE's settings document (boone 2026-10-22). Optional: without it the
+    # build reads the SE's settings from Supabase as before.
+    settings: dict | None = None,
 ) -> dict:
     """Start a full ThoughtSpot demo build from a prospect brief.
 
@@ -1453,6 +1504,17 @@ def build_demo_from_brief(
         environment: REQUIRED. Which environment this demo is for — "prod" or "staging"
                 ("production"/"stage" are accepted and normalised). Recorded with the run;
                 a build will not start without a valid value.
+        settings: Optional. The SE's DemoPrep settings as ONE JSON object (schema
+                "1.0"; shape in docs/demoprep_settings_payload.example.json), produced
+                by the TSE settings app. When sent, the build takes model, data size,
+                column naming style, object prefix, liveboard name, tag, share-with
+                and geo scope from it and does not read the SE's settings from
+                Supabase at all. An explicit owner_email or ts_url wins over the
+                document's owner_email / thoughtspot.url; a blank ts_url falls back
+                to the document's thoughtspot.url, then its environment_label. A
+                document with an unknown key, a value outside its allowed set, or a
+                schema_version this server does not understand is refused before
+                anything is built (the error names the key).
         custom_mcp_demo: Optional, OFF by default. Set true to also get a "Custom MCP
                 Demo — GitHub Issues → Spotter" walkthrough for this demo: a suggested
                 GitHub repo name, 4 GitHub issues written from the deployed model's
@@ -1600,6 +1662,24 @@ def build_demo_from_brief(
     except ValueError as e:
         return {"status": "failed", "errors": [str(e)]}
 
+    # The SE's settings document (boone 2026-10-22): validated here so a bad one is
+    # refused before a slot is taken, applied in _run_build in place of the
+    # Supabase per-key lookups. Explicit owner_email / ts_url win over it.
+    build_settings = None
+    if settings is not None:
+        try:
+            build_settings = parse_settings_payload(settings)
+        except SettingsPayloadError as e:
+            return {"status": "failed", "errors": [f"settings: {e}"]}
+        owner_email = (owner_email or "").strip() or build_settings.owner_email
+        if not (ts_url or "").strip():
+            try:
+                ts_url = build_settings.ts_url or (
+                    _ts_url_for_label(build_settings.ts_environment_label)
+                    if build_settings.ts_environment_label else "")
+            except RuntimeError as e:
+                return {"status": "failed", "errors": [f"settings: {e}"]}
+
     # Resolve the ThoughtSpot target up front (URL from the request or the default,
     # key chosen by instance) so a bad URL / missing key fails fast — before we
     # take the single build slot.
@@ -1687,7 +1767,8 @@ def build_demo_from_brief(
                        custom_mcp_demo=custom_mcp_demo,
                        header_tiles=header_tiles,
                        schema_style=schema_style,
-                       homepage_screenshot=_shot)
+                       homepage_screenshot=_shot,
+                       build_settings=build_settings)
         finally:
             _build_sem.release()
 

sprint_2026_04.md

@@ -1613,5 +1613,57 @@ Source-level edits deferred to v2.
 
 ---
 
-*Last updated: October 20, 2026 — portal update tools ON TEST-MCP c0c09a2, verified
-end to end; prod pending boone*
+## October 22, 2026 — DemoPrep settings document for Agent Q (branch `claude/demo-prep-settings-json-547af4`, off `b918bd8` = test and prod tip)
+
+A separate TSE app will own DemoPrep settings. Agent Q hands the SE's settings to
+the build as ONE JSON document, so DemoPrep stops reading an SE's settings from
+Supabase per run. Goal (boone): get the app moved.
+
+### Done
+- [x] Settings inventory ✅ `docs/demoprep_settings_inventory.md` — all four layers
+  (per-user Supabase, admin Supabase, Space env, per-call args); consumer per key;
+  which the MCP path honoured before (3 of 7 meaningful ones were ignored:
+  `column_naming_style`, `liveboard_name`, `share_with`)
+- [x] Live-data audit ✅ Supabase `user_settings`: 744 rows / 46 users; everyone on
+  the defaults; 12 users still carry `gpt-5.5` (resolves to Opus at run time)
+- [x] Decisions (boone, 10-22) ✅ App tab keeps Supabase; non-secret Snowflake block
+  travels as `admin.snowflake`, key never in the document; `geo_scope` keep + list;
+  `share_with` as a list; dead per-user fields dropped; `schema_version` check yes
+- [x] The document ✅ `docs/demoprep_settings_payload.example.json` (schema 1.0;
+  gitignored by the blanket `*.json` rule — `git add -f`)
+- [x] Reader ✅ `demoprep_app/settings/payload.py` — `parse_settings_payload()`
+  (schema major 1, allowed values, unknown keys refused, never partial) and
+  `apply_build_settings()` (exact keys the pipeline reads); the data-size preset
+  table lives there now
+- [x] MCP wiring ✅ `build_demo_from_brief(..., settings: dict | None)`; explicit
+  `owner_email` / `ts_url` win, else the document (`thoughtspot.url`, then
+  `environment_label` via `_ts_url_for_label()`); refused before target resolution
+  or a slot; `_run_build` applies it and records `settings_source` +
+  `settings_schema_version` on the run
+- [x] No Supabase for a document-driven run ✅ `ChatDemoInterface(...,
+  settings_from_supabase=False)` + the three mid-run `load_gradio_settings` re-reads
+  in chat_interface guarded by `_settings_source == 'payload'`
+- [x] Tests ✅ `tests/test_settings_payload.py` (30) + `tests/test_mcp_settings_document.py`
+  (12); one fixture stub updated (`test_custom_mcp_demo_pack.py` loader signature);
+  targeted MCP/controller suites green
+- [x] Brief for the settings-app builder ✅ `docs/settings_app_agent_brief.md`
+  (paste-ready: contract, rules, Agent Q handoff, phase-2 Supabase table)
+- [x] Flag registry ✅ `docs/agent_q_flags.md` — `settings` row + change log
+
+### Open
+- [ ] Push to test-mcp when boone calls it (Space idle; refresh Agent Q's tool list after)
+- [ ] Settings app: emit the document per SE (the example file is the contract)
+- [ ] Agent Q: fetch and pass `settings`
+- [ ] Phase 2, Supabase: table `demoprep_settings` (DDL in the inventory doc),
+  `load_settings_document()`, order = call arg → row → legacy per-key until cutover;
+  `admin.*` moves to a boot-time document read
+- [ ] Drop the dead per-user fields from the Settings tab once the app is live
+- [ ] Found on the way: README env names (`MCP_OWNER_EMAIL` / `MCP_TS_ENV_LABEL` vs the
+  real `TS_USER_DEFAULT` / `TS_ENV_URL_DEFAULT`) and the `OPENAI_API_KEY` check in
+  `validate_required_settings()`
+
+---
+
+*Last updated: October 22, 2026 — settings document (`settings` on
+`build_demo_from_brief`) built and tested on `claude/demo-prep-settings-json-547af4`;
+not pushed; settings-app brief written*

tests/test_custom_mcp_demo_pack.py

@@ -328,7 +328,10 @@ def offline(monkeypatch):
     monkeypatch.setattr(cdw_connector, "SnowflakeDeployer", _FakeSnowflakeDeployer)
     monkeypatch.setattr(thoughtspot_deployer, "ThoughtSpotDeployer", _FakeTSDeployer)
     monkeypatch.setattr(smart_data_adjuster, "SmartDataAdjuster", _NoAdjuster)
-    monkeypatch.setattr(CI.ChatDemoInterface, "load_default_settings", lambda self: {})
+    # Mirrors the real signature: the constructor passes from_supabase= (a run
+    # driven by a settings document skips the Supabase read entirely).
+    monkeypatch.setattr(CI.ChatDemoInterface, "load_default_settings",
+                        lambda self, from_supabase=True: {})
     # The deploy loop polls its worker every 2s; keep the poll, drop the wait.
     _real_sleep = time.sleep
     monkeypatch.setattr(time, "sleep", lambda s: _real_sleep(min(s, 0.01)))

tests/test_mcp_settings_document.py

@@ -0,0 +1,224 @@
+"""`settings` on build_demo_from_brief: the SE's settings document replaces Supabase.
+
+Run: pytest tests/test_mcp_settings_document.py --noconftest
+
+boone 2026-10-22: a separate TSE app owns DemoPrep settings and Agent Q hands
+the document to the build, so DemoPrep stops reading an SE's settings from
+Supabase per run. These tests pin:
+
+  * the registered tool takes `settings` as an object and documents it;
+  * a bad document is refused before the ThoughtSpot target is resolved or a
+    slot is taken, naming the key;
+  * owner_email / ts_url come from the document when the call leaves them
+    blank, and explicit arguments win;
+  * a label-only document resolves through the TS_ENV table;
+  * the worker receives the parsed document, and a controller built from it
+    never touches Supabase settings (constructor and both mid-run re-reads).
+"""
+from __future__ import annotations
+
+import inspect
+import os
+import re
+import threading
+from pathlib import Path
+
+import pytest
+
+os.environ.setdefault("MCP_TRANSPORT", "stdio")
+
+import mcp_server as M  # noqa: E402  (sets DEMOPREP_NO_AUTH before chat_interface loads)
+import chat_interface as CI  # noqa: E402
+from demoprep_app.settings.payload import BuildSettings, SCHEMA_VERSION  # noqa: E402
+
+REQUIRED = {"brief": "a brief", "company_name": "Acme",
+            "salesforce_opportunity_id": "006TV00000ffxVxYAI", "environment": "prod"}
+DOC = {
+    "schema_version": SCHEMA_VERSION, "source": "test",
+    "owner_email": "doc.owner@thoughtspot.com",
+    "thoughtspot": {"environment_label": "secloud - primary",
+                    "url": "https://se-thoughtspot-cloud.thoughtspot.cloud"},
+    "build": {"data_size": "Small", "column_naming_style": "snake_case", "tag_name": "t"},
+}
+ENV_TABLE = {
+    "TS_ENV_1_LABEL": "secloud - primary",
+    "TS_ENV_1_URL": "https://se-thoughtspot-cloud.thoughtspot.cloud",
+    "TS_ENV_1_KEY_VAR": "key-secloud",
+    "TS_ENV_2_LABEL": "sebe - se",
+    "TS_ENV_2_URL": "https://sebe.thoughtspotstaging.cloud",
+    "TS_ENV_2_KEY_VAR": "key-sebe",
+}
+
+
+@pytest.fixture
+def env_table(monkeypatch):
+    for i in range(1, 21):
+        for part in ("LABEL", "URL", "KEY_VAR"):
+            name = f"TS_ENV_{i}_{part}"
+            if name in ENV_TABLE:
+                monkeypatch.setenv(name, ENV_TABLE[name])
+            else:
+                monkeypatch.delenv(name, raising=False)
+    monkeypatch.delenv("TS_ENV_URL_DEFAULT", raising=False)
+    monkeypatch.delenv("TS_AUTH_KEY", raising=False)
+
+
+def _precheck_ok(url, key, owner):
+    return {"outcome": "ok", "blocking": False, "http_status": 200, "reason": "",
+            "host": M._host_of(url), "elapsed_ms": 1, "message": ""}
+
+
+@pytest.fixture
+def captured(monkeypatch):
+    """Run the tool up to the worker; capture what _run_build is handed."""
+    monkeypatch.setattr(M, "_login_precheck", _precheck_ok)
+    done = threading.Event()
+    seen: dict = {}
+
+    def fake_run_build(*args, **kwargs):
+        seen["args"], seen["kwargs"] = args, kwargs
+        with M._state_lock:
+            M._active_builds.pop(args[0], None)
+        done.set()
+
+    monkeypatch.setattr(M, "_run_build", fake_run_build)
+    seen["done"] = done
+    return seen
+
+
+# ------------------------------------------------------------ the parameter
+
+def _documented_args(func) -> list[str]:
+    names = []
+    for line in (inspect.getdoc(func) or "").split("Args:", 1)[1].splitlines():
+        if not line.strip():
+            continue
+        if not line.startswith(" "):
+            break
+        m = re.match(r"^    ([a-z_][a-z0-9_]*):", line)
+        if m:
+            names.append(m.group(1))
+    return names
+
+
+def test_it_is_optional_and_documented_for_agent_q():
+    p = inspect.signature(M.build_demo_from_brief).parameters["settings"]
+    assert p.default is None and p.kind is inspect.Parameter.KEYWORD_ONLY
+    assert "settings" in _documented_args(M.build_demo_from_brief)
+    doc = inspect.getdoc(M.build_demo_from_brief)
+    assert "demoprep_settings_payload.example.json" in doc
+
+
+def test_the_registered_tool_takes_an_object():
+    tool = M.mcp._tool_manager.get_tool("build_demo_from_brief")
+    assert "settings" in tool.parameters["properties"]
+    model = tool.fn_metadata.arg_model
+    assert model.model_validate(REQUIRED).settings is None
+    assert model.model_validate({**REQUIRED, "settings": DOC}).settings == DOC
+
+
+# ---------------------------------------------------------------- refusals
+
+def test_a_bad_document_is_refused_before_anything_is_resolved(monkeypatch):
+    def boom(*a, **k):
+        raise AssertionError("target resolution ran for a refused document")
+    monkeypatch.setattr(M, "_resolve_ts_target", boom)
+    monkeypatch.setattr(M, "_login_precheck", boom)
+    monkeypatch.setattr(M, "_run_build", boom)
+    active_before = set(M._active_builds)
+    for bad, key in (({**DOC, "schema_version": "2.0"}, "schema_version"),
+                     ({**DOC, "build": {"data_size": "Large"}}, "build.data_size"),
+                     ({**DOC, "buidl": {}}, "unknown top-level key")):
+        out = M.build_demo_from_brief(**REQUIRED, settings=bad)
+        assert out["status"] == "failed" and out["errors"][0].startswith("settings:"), out
+        assert key in out["errors"][0]
+    assert set(M._active_builds) == active_before
+
+
+def test_an_unknown_label_with_no_url_is_refused_with_the_known_labels(env_table, monkeypatch):
+    monkeypatch.setattr(M, "_run_build", lambda *a, **k: pytest.fail("built"))
+    doc = {**DOC, "thoughtspot": {"environment_label": "pmm"}}
+    out = M.build_demo_from_brief(**REQUIRED, settings=doc)
+    assert out["status"] == "failed"
+    assert "labelled 'pmm'" in out["errors"][0] and "secloud - primary" in out["errors"][0]
+
+
+# ------------------------------------------------------------ precedence
+
+def test_owner_and_target_come_from_the_document_when_the_call_is_blank(env_table, captured):
+    out = M.build_demo_from_brief(**REQUIRED, settings=DOC)
+    assert out["status"] == "started", out
+    assert captured["done"].wait(5)
+    run_id, brief, company, use_case, company_url, ts_url, key, owner, *_ = captured["args"]
+    assert owner == "doc.owner@thoughtspot.com"
+    assert ts_url == "https://se-thoughtspot-cloud.thoughtspot.cloud" and key == "key-secloud"
+    bs = captured["kwargs"]["build_settings"]
+    assert isinstance(bs, BuildSettings)
+    assert bs.data_size == "Small" and bs.column_naming_style == "snake_case" and bs.tag_name == "t"
+    assert M._build_sem.acquire(blocking=False) and (M._build_sem.release() or True)
+
+
+def test_explicit_owner_and_ts_url_win_over_the_document(env_table, captured):
+    out = M.build_demo_from_brief(**REQUIRED, settings=DOC,
+                                  owner_email="explicit@thoughtspot.com",
+                                  ts_url="https://sebe.thoughtspotstaging.cloud")
+    assert out["status"] == "started", out
+    assert captured["done"].wait(5)
+    _, _, _, _, _, ts_url, key, owner, *_ = captured["args"]
+    assert owner == "explicit@thoughtspot.com"
+    assert ts_url == "https://sebe.thoughtspotstaging.cloud" and key == "key-sebe"
+
+
+def test_a_label_only_document_resolves_through_the_env_table(env_table, captured):
+    doc = {**DOC, "thoughtspot": {"environment_label": "SEBE - SE"}}
+    out = M.build_demo_from_brief(**REQUIRED, settings=doc)
+    assert out["status"] == "started", out
+    assert captured["done"].wait(5)
+    _, _, _, _, _, ts_url, key, *_ = captured["args"]
+    assert ts_url == "https://sebe.thoughtspotstaging.cloud" and key == "key-sebe"
+
+
+def test_without_a_document_nothing_changes(env_table, captured):
+    out = M.build_demo_from_brief(**REQUIRED, owner_email="x@thoughtspot.com",
+                                  ts_url="https://sebe.thoughtspotstaging.cloud")
+    assert out["status"] == "started", out
+    assert captured["done"].wait(5)
+    assert captured["kwargs"]["build_settings"] is None
+
+
+def test_ts_url_for_label_is_case_insensitive_and_fails_loud(env_table):
+    assert M._ts_url_for_label("Secloud - Primary") == "https://se-thoughtspot-cloud.thoughtspot.cloud"
+    with pytest.raises(RuntimeError, match="Known labels: 'secloud - primary', 'sebe - se'"):
+        M._ts_url_for_label("nope")
+
+
+# ------------------------------------------------- the controller and Supabase
+
+def test_a_controller_built_from_a_document_never_reads_supabase_settings(monkeypatch):
+    def boom(*a, **k):
+        raise AssertionError("load_gradio_settings was called for a document-driven run")
+    monkeypatch.setattr(CI, "load_gradio_settings", boom)
+    c = CI.ChatDemoInterface(user_email="se@thoughtspot.com", settings_from_supabase=False)
+    assert c._settings_source == "payload"
+    assert c.settings["model"] and c.settings["validation_mode"] == "Off"
+    assert CI.ChatDemoInterface.__init__.__kwdefaults__ == {"settings_from_supabase": True}
+
+
+def test_the_mid_run_rereads_are_guarded():
+    """run_deployment_streaming and _run_thoughtspot_deployment re-read the SE's
+    Supabase settings mid-run. Each remaining call must sit under the
+    _settings_source guard, or a document-driven run would read Supabase after all."""
+    src = Path(CI.__file__).read_text().splitlines()
+    calls = [i for i, ln in enumerate(src)
+             if "load_gradio_settings(self._get_effective_user_email())" in ln]
+    assert calls, "the re-reads moved; update this test"
+    for i in calls:
+        window = "\n".join(src[max(0, i - 4):i])
+        assert "_settings_source == 'payload'" in window, f"unguarded Supabase re-read at line {i + 1}"
+
+
+def test_the_worker_uses_the_document_and_records_its_source():
+    src = inspect.getsource(M._run_build)
+    assert "settings_from_supabase=build_settings is None" in src
+    assert "apply_build_settings(" in src
+    assert "'settings_source': 'payload' if build_settings is not None else 'supabase'" in src

tests/test_payload_capture_is_complete.py

@@ -38,7 +38,8 @@ def test_capture_includes_every_parameter_of_the_tool():
                monetize=True, tiers=True, pinning=False, salesforce_opportunity_id="",
                environment="", schema_style="simple", apply_brand_theme=False,
                brand_theme=None, custom_mcp_demo=False,
-               logo_tile=False, insight_tile=False, homepage_screenshot=""):
+               logo_tile=False, insight_tile=False, homepage_screenshot="",
+               settings=None):  # settings document, 2026-10-22
         return M._call_payload(inspect.currentframe())
 
     got = set(sample())

tests/test_payload_reaches_the_database.py

@@ -125,7 +125,8 @@ def test_tool_signature_survives_the_entire_path():
                monetize=True, tiers=True, pinning=False, salesforce_opportunity_id="",
                environment="", schema_style="simple", apply_brand_theme=False,
                brand_theme=None, custom_mcp_demo=False,
-               logo_tile=False, insight_tile=False, homepage_screenshot=""):
+               logo_tile=False, insight_tile=False, homepage_screenshot="",
+               settings=None):  # settings document, 2026-10-22
         return M._call_payload(inspect.currentframe())
 
     results = captured_row(sample())

tests/test_settings_payload.py

@@ -0,0 +1,199 @@
+"""The settings document (schema 1.x): parse rules and the controller apply step.
+
+Run: pytest tests/test_settings_payload.py --noconftest
+
+Pure: imports only demoprep_app.settings.payload and llm_config. The document
+is the contract between the TSE settings app, Agent Q and DemoPrep
+(docs/demoprep_settings_inventory.md); these tests pin what it accepts, what it
+refuses, and exactly which controller keys it writes.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from demoprep_app.settings.payload import (
+    DATA_SIZE_PRESETS, SCHEMA_VERSION, SettingsPayloadError,
+    apply_build_settings, parse_settings_payload,
+)
+from llm_config import DEFAULT_LLM_MODEL, UI_MODEL_CHOICES
+
+EXAMPLE = Path(__file__).resolve().parents[1] / "docs" / "demoprep_settings_payload.example.json"
+
+
+def _doc(**build) -> dict:
+    d = {"schema_version": SCHEMA_VERSION, "source": "test", "owner_email": "se@thoughtspot.com",
+         "thoughtspot": {"environment_label": "secloud - primary",
+                         "url": "https://se-thoughtspot-cloud.thoughtspot.cloud"},
+         "build": {}}
+    d["build"].update(build)
+    return d
+
+
+# ------------------------------------------------------------- the example
+
+def test_the_checked_in_example_parses():
+    """docs/demoprep_settings_payload.example.json is what the settings app is
+    told to produce; it must always be a valid document."""
+    s = parse_settings_payload(json.loads(EXAMPLE.read_text()))
+    assert s.schema_version == SCHEMA_VERSION
+    assert s.model in UI_MODEL_CHOICES
+    assert (s.fact_table_rows, s.dim_table_rows) == DATA_SIZE_PRESETS[s.data_size]
+    assert s.admin_snowflake["database"] == "DEMOBUILD"
+    assert s.ts_url == "https://se-thoughtspot-cloud.thoughtspot.cloud"
+
+
+# ---------------------------------------------------------------- defaults
+
+def test_absent_build_keys_take_the_settings_tab_defaults():
+    s = parse_settings_payload({"schema_version": "1.0"})
+    assert s.model == DEFAULT_LLM_MODEL
+    assert s.data_size == "Medium"
+    assert (s.fact_table_rows, s.dim_table_rows) == (10000, 500)
+    assert s.column_naming_style == "Regular Case"
+    assert s.geo_scope == "USA Only"
+    assert s.share_with == () and s.liveboard_name == "" and s.tag_name == ""
+    assert s.owner_email == "" and s.ts_url == "" and s.ts_environment_label == ""
+
+
+def test_data_size_preset_drives_rows_unless_rows_are_explicit():
+    assert parse_settings_payload(_doc(data_size="Small")).fact_table_rows == 1000
+    s = parse_settings_payload(_doc(data_size="Small", fact_table_rows=2500))
+    assert (s.fact_table_rows, s.dim_table_rows) == (2500, 50)
+
+
+def test_share_with_accepts_a_list_or_the_comma_string_the_app_stores():
+    assert parse_settings_payload(_doc(share_with=["a@x.com", " b@x.com ", ""])).share_with == ("a@x.com", "b@x.com")
+    assert parse_settings_payload(_doc(share_with="a@x.com, Group One")).share_with == ("a@x.com", "Group One")
+
+
+def test_effective_share_with_falls_back_to_the_admin_default_only():
+    d = _doc(share_with=[])
+    d["admin"] = {"share_with_default": ["mike.boone@thoughtspot.com"]}
+    assert parse_settings_payload(d).effective_share_with == "mike.boone@thoughtspot.com"
+    d["build"]["share_with"] = ["se@x.com"]
+    assert parse_settings_payload(d).effective_share_with == "se@x.com"
+
+
+def test_owner_email_is_normalised_lowercase():
+    d = _doc(); d["owner_email"] = " SE.Name@ThoughtSpot.com "
+    assert parse_settings_payload(d).owner_email == "se.name@thoughtspot.com"
+
+
+# ---------------------------------------------------------------- refusals
+
+@pytest.mark.parametrize("version", ["2.0", "0.9", "1.1", "1", "", None, "one"])
+def test_a_schema_version_this_server_does_not_read_is_refused(version):
+    d = _doc(); d["schema_version"] = version
+    with pytest.raises(SettingsPayloadError, match="schema_version"):
+        parse_settings_payload(d)
+
+
+def test_unknown_keys_are_refused_not_ignored():
+    d = _doc(); d["buidl"] = {}
+    with pytest.raises(SettingsPayloadError, match="unknown top-level key"):
+        parse_settings_payload(d)
+    with pytest.raises(SettingsPayloadError, match="build: unknown key"):
+        parse_settings_payload(_doc(colum_naming_style="snake_case"))
+
+
+def test_dollar_keys_are_comments():
+    d = _doc(); d["$comment"] = "free text"; d["build"]["$note"] = "ok"
+    parse_settings_payload(d)
+
+
+@pytest.mark.parametrize("key,bad", [
+    ("model", "gpt-5.5"),
+    ("data_size", "Large"),
+    ("column_naming_style", "kebab-case"),
+    ("geo_scope", "Europe"),
+])
+def test_a_value_outside_its_allowed_set_is_refused_with_the_choices(key, bad):
+    with pytest.raises(SettingsPayloadError) as e:
+        parse_settings_payload(_doc(**{key: bad}))
+    assert key in str(e.value) and "is not one of" in str(e.value)
+
+
+@pytest.mark.parametrize("bad", ["10000", 0, -5, True, 1.5])
+def test_row_counts_must_be_positive_integers(bad):
+    with pytest.raises(SettingsPayloadError, match="fact_table_rows"):
+        parse_settings_payload(_doc(fact_table_rows=bad))
+
+
+def test_wrong_shapes_are_refused():
+    with pytest.raises(SettingsPayloadError, match="settings must be an object"):
+        parse_settings_payload("not a dict")  # type: ignore[arg-type]
+    d = _doc(); d["build"] = ["list"]
+    with pytest.raises(SettingsPayloadError, match="build: must be an object"):
+        parse_settings_payload(d)
+    with pytest.raises(SettingsPayloadError, match="build.tag_name: must be a string"):
+        parse_settings_payload(_doc(tag_name=7))
+    with pytest.raises(SettingsPayloadError, match="build.share_with"):
+        parse_settings_payload(_doc(share_with=[1, 2]))
+
+
+def test_admin_section_is_validated_and_log_level_is_optional():
+    d = _doc(); d["admin"] = {"log_level": "loud"}
+    with pytest.raises(SettingsPayloadError, match="admin.log_level"):
+        parse_settings_payload(d)
+    d["admin"] = {"snowflake": {"account": "X", "region": "us"}}
+    with pytest.raises(SettingsPayloadError, match="snowflake: unknown key"):
+        parse_settings_payload(d)
+    d["admin"] = {"snowflake": {"account": " X "}}
+    s = parse_settings_payload(d)
+    assert s.admin_snowflake == {"account": "X"} and s.admin_log_level == ""
+
+
+def test_ui_defaults_are_accepted_but_not_part_of_build_settings():
+    d = _doc(); d["ui_defaults"] = {"validation_mode": "On", "vertical": "Retail"}
+    parse_settings_payload(d)
+    d["ui_defaults"] = {"validatoin_mode": "On"}
+    with pytest.raises(SettingsPayloadError, match="ui_defaults: unknown key"):
+        parse_settings_payload(d)
+
+
+# ------------------------------------------------------------------- apply
+
+def test_apply_writes_exactly_the_keys_the_pipeline_reads():
+    """These names are what chat_interface / thoughtspot_deployer read today
+    (fact_table_size, column_naming_style, ...). Renaming one here without
+    renaming the reader would silently drop the setting."""
+    s = parse_settings_payload(_doc(
+        model=UI_MODEL_CHOICES[-1], data_size="Small", column_naming_style="snake_case",
+        object_naming_prefix="ACME", liveboard_name="Acme Board", tag_name="demo",
+        share_with=["a@x.com", "b@x.com"], geo_scope="International",
+        existing_model_guid="abc-123"))
+    target = {"thoughtspot_url": "keep", "model": "old"}
+    applied = apply_build_settings(target, s, share_with_fallback="ops@x.com")
+    assert applied == {
+        "model": UI_MODEL_CHOICES[-1],
+        "fact_table_size": "1000", "dim_table_size": "50",
+        "column_naming_style": "snake_case",
+        "object_naming_prefix": "ACME",
+        "liveboard_name": "Acme Board",
+        "tag_name": "demo",
+        "share_with": "a@x.com,b@x.com",
+        "geo_scope": "International",
+        "use_existing_model": True, "existing_model_guid": "abc-123",
+        "validation_mode": "Off",
+    }
+    assert target["thoughtspot_url"] == "keep", "apply must not touch keys it does not own"
+    for k, v in applied.items():
+        assert target[k] == v
+
+
+def test_apply_uses_the_server_fallback_only_when_nobody_is_named():
+    s = parse_settings_payload(_doc())
+    assert apply_build_settings({}, s, share_with_fallback="ops@x.com")["share_with"] == "ops@x.com"
+    s = parse_settings_payload(_doc(share_with=["se@x.com"]))
+    assert apply_build_settings({}, s, share_with_fallback="ops@x.com")["share_with"] == "se@x.com"
+
+
+def test_row_counts_are_strings_on_the_controller():
+    """The pipeline does int(self.settings['fact_table_size']) on a string, as the
+    App tab stores it. Keep the type the reader expects."""
+    s = parse_settings_payload(_doc(fact_table_rows=3333, dim_table_rows=77))
+    applied = apply_build_settings({}, s)
+    assert applied["fact_table_size"] == "3333" and applied["dim_table_size"] == "77"