synth-ai 0.2.8.dev2__py3-none-any.whl → 0.4.3__py3-none-any.whl

synth_ai/{demos → cli/demo_apps}/core/cli.py

@@ -1,19 +1,45 @@
 from __future__ import annotations
 
-import argparse
+import contextlib
 import json
 import os
-import sys
-import time
-from pathlib import Path
-from typing import Any, Dict, Callable
 import shutil
 import stat
+import sys
 import textwrap
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from synth_ai.cli.demo_apps.demo_registry import (
+    DemoTemplate,
+    get_demo_template,
+    list_demo_templates,
+)
+from synth_ai.cli.demo_apps.demo_task_apps import core as demo_core
+from synth_ai.cli.demo_apps.demo_task_apps.core import DEFAULT_TASK_APP_SECRET_NAME, DemoEnv
+from synth_ai.core.process import get_subprocess_env, should_filter_log_line
+
+try:
+    from synth_ai.handshake import HandshakeError, run_handshake  # type: ignore[import-untyped]
+except ImportError:
+    # handshake module may not exist in all environments
+    HandshakeError = Exception  # type: ignore[assignment,misc]
+    def run_handshake() -> None:  # type: ignore[misc]
+        pass
+
 
-from synth_ai.demos.demo_task_apps import core as demo_core
-from synth_ai.handshake import run_handshake, HandshakeError
-from synth_ai.demos.demo_task_apps.core import DemoEnv
+def _key_preview(value: str, label: str) -> str:
+    """Return a short descriptor for a secret without leaking the full value."""
+    try:
+        text = value or ""
+        length = len(text)
+        prefix = text[:6] if length >= 6 else text
+        suffix = text[-5:] if length >= 5 else text
+        return f"{label} len={length} prefix={prefix} last5={suffix}"
+    except Exception:
+        return f"{label} len=0"
 
 
 def _is_modal_public_url(u: str) -> bool:
@@ -26,35 +52,75 @@ def _is_modal_public_url(u: str) -> bool:
         return False
 
 
-def cmd_setup(_args: argparse.Namespace) -> int:
-    # 1) Always perform SDK handshake and overwrite .env with returned keys
+def setup() -> int:
+    # Change to demo directory if stored
+    demo_dir = demo_core.load_demo_dir()
+    if demo_dir and os.path.isdir(demo_dir):
+        os.chdir(demo_dir)
+        print(f"Using demo directory: {demo_dir}")
+
+    # 1) Try to fetch keys from frontend; fall back to manual input if fetch fails
+    synth_key = ""
+    rl_env_key = ""
+    org_name = "this organization"
+
     try:
         print("\n⏳ Connecting SDK to your browser session…")
         res = run_handshake()
-        user = res.get("user") or {}
-        org = res.get("org") or {}
-        keys = res.get("keys") or {}
-        synth_key = str(keys.get("synth") or "").strip()
-        rl_env_key = str(keys.get("rl_env") or "").strip()
-        if not synth_key or not rl_env_key:
-            raise HandshakeError("handshake returned missing keys")
-        # Overwrite .env with the latest values from the account/org
-        demo_core.persist_dotenv_values({
+        # Type narrowing for dict access - run_handshake returns dict[str, Any] | None
+        res_dict: dict[str, Any] = res if isinstance(res, dict) else {}
+        org_val = res_dict.get("org")  # type: ignore[misc]
+        org: dict[str, Any] = org_val if isinstance(org_val, dict) else {}
+        keys_val = res_dict.get("keys")  # type: ignore[misc]
+        keys: dict[str, Any] = keys_val if isinstance(keys_val, dict) else {}
+        synth_key = str(keys.get("synth") or "").strip()  # type: ignore[misc]
+        rl_env_key = str(keys.get("rl_env") or "").strip()  # type: ignore[misc]
+        org_name = org.get("name") or "this organization"  # type: ignore[misc]
+        print(f"✅ Connected to {org_name}!")
+    except (HandshakeError, Exception) as e:
+        print(f"⚠️  Failed to fetch keys from frontend: {e}")
+        print("Falling back to manual entry...")
+
+    # Prompt for manual input if any key is missing
+    if not synth_key:
+        try:
+            synth_key = input(
+                "Failed to fetch your Synth API key. Please enter your Synth API key here:\n> "
+            ).strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nSetup cancelled.")
+            return 1
+        if not synth_key:
+            print("Synth API key is required.")
+            return 1
+
+    if not rl_env_key:
+        try:
+            rl_env_key = input(
+                "Failed to fetch your RL Environment API key. Please enter your RL Environment API key here:\n> "
+            ).strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nSetup cancelled.")
+            return 1
+        if not rl_env_key:
+            print("RL Environment API key is required.")
+            return 1
+
+    # Persist both keys to .env
+    dotenv_path = demo_core.persist_dotenv_values(
+        {
             "SYNTH_API_KEY": synth_key,
             "ENVIRONMENT_API_KEY": rl_env_key,
-        })
-        org_name = (org.get("name") or "this organization")
-        print(f"✅ Connected to {org_name}!")
-    except HandshakeError as e:
-        print(f"Handshake failed: {e}")
-        return 1
-    except Exception as e:
-        print(f"Unexpected handshake error: {e}")
-        return 1
+        }
+    )
+
+    # Store .env path for subsequent commands
+    demo_core.persist_env_file_path(dotenv_path)
 
     # 2) Reload env after handshake to pick up values from .env (suppress env prints)
-    import io
     import contextlib
+    import io
+
     _buf = io.StringIO()
     with contextlib.redirect_stdout(_buf):
         env = demo_core.load_env()
@@ -71,22 +137,22 @@ def cmd_setup(_args: argparse.Namespace) -> int:
             return
         current = env.task_app_base_url
         needs_lookup = False
-        if not current:
-            needs_lookup = True
-        elif not _is_modal_public_url(current):
+        if not current or not _is_modal_public_url(current):
             needs_lookup = True
         if not needs_lookup:
             return
-        code, out = _popen_capture([
-            "uv",
-            "run",
-            "python",
-            "-m",
-            "modal",
-            "app",
-            "url",
-            env.task_app_name,
-        ])
+        code, out = _popen_capture(
+            [
+                "uv",
+                "run",
+                "python",
+                "-m",
+                "modal",
+                "app",
+                "url",
+                env.task_app_name,
+            ]
+        )
         if code != 0 or not out:
             return
         new_url = ""
@@ -100,7 +166,6 @@ def cmd_setup(_args: argparse.Namespace) -> int:
             dotenv_values = {
                 "TASK_APP_BASE_URL": new_url,
                 "TASK_APP_NAME": env.task_app_name,
-                "TASK_APP_SECRET_NAME": env.task_app_secret_name or f"{env.task_app_name}-secret",
             }
             demo_core.persist_dotenv_values(dotenv_values)
             os.environ["TASK_APP_BASE_URL"] = new_url
@@ -108,7 +173,7 @@ def cmd_setup(_args: argparse.Namespace) -> int:
 
     # Keys have been written already via handshake; avoid any interactive prompts
     synth_key = env.synth_api_key.strip()
-    if not local_env.get("SYNTH_API_KEY") and synth_key:
+    if not local_env.get("SYNTH_API_KEY") and synth_key:  # type: ignore[misc]
         demo_core.persist_dotenv_values({"SYNTH_API_KEY": synth_key})
         _refresh_env()
 
@@ -117,15 +182,16 @@ def cmd_setup(_args: argparse.Namespace) -> int:
 
     _maybe_fix_task_url()
 
-    ok_backend = False
-    ok_task = False
     if env.dev_backend_url:
-        api = env.dev_backend_url.rstrip("/") + ("" if env.dev_backend_url.endswith("/api") else "/api")
-        ok_backend = demo_core.assert_http_ok(api + "/health", method="GET")
+        api = env.dev_backend_url.rstrip("/") + (
+            "" if env.dev_backend_url.endswith("/api") else "/api"
+        )
+        demo_core.assert_http_ok(api + "/health", method="GET")
         # Intentionally suppress backend health print for concise output
     if env.task_app_base_url:
-        ok_task = demo_core.assert_http_ok(env.task_app_base_url.rstrip("/") + "/health", method="GET") or \
-                  demo_core.assert_http_ok(env.task_app_base_url.rstrip("/"), method="GET")
+        demo_core.assert_http_ok(
+            env.task_app_base_url.rstrip("/") + "/health", method="GET"
+        ) or demo_core.assert_http_ok(env.task_app_base_url.rstrip("/"), method="GET")
         # Intentionally suppress task app health print
     else:
         print("\nSet your task app URL by running:\nuvx synth-ai rl_demo deploy\n")
@@ -133,13 +199,19 @@ def cmd_setup(_args: argparse.Namespace) -> int:
     # Omit uv version print to keep output concise
 
     # Keep exit code neutral; not all checks are critical for pairing
+    print(f"\nKeys saved to: {dotenv_path}")
     return 0
 
 
-def _popen_capture(cmd: list[str], cwd: str | None = None, env: dict | None = None) -> tuple[int, str]:
+def _popen_capture(
+    cmd: list[str], cwd: str | None = None, env: dict | None = None
+) -> tuple[int, str]:
     import subprocess
+
     try:
-        proc = subprocess.Popen(cmd, cwd=cwd, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        proc = subprocess.Popen(
+            cmd, cwd=cwd, env=get_subprocess_env(env), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
+        )
         out, _ = proc.communicate()
         return int(proc.returncode or 0), out or ""
     except Exception as e:
@@ -156,7 +228,7 @@ def _popen_stream(cmd: list[str], cwd: str | None = None, env: dict | None = Non
         proc = subprocess.Popen(
             cmd,
             cwd=cwd,
-            env=env,
+            env=get_subprocess_env(env),
             stdout=subprocess.PIPE,
             stderr=subprocess.STDOUT,
             text=True,
@@ -169,7 +241,8 @@ def _popen_stream(cmd: list[str], cwd: str | None = None, env: dict | None = Non
     def _pump(stdout) -> None:
         try:
             for line in stdout:
-                print(line.rstrip())
+                if not should_filter_log_line(line):
+                    print(line.rstrip())
         except Exception:
             pass
 
@@ -183,7 +256,9 @@ def _popen_stream(cmd: list[str], cwd: str | None = None, env: dict | None = Non
     return int(proc.returncode or 0)
 
 
-def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | None = None) -> tuple[int, str]:
+def _popen_stream_capture(
+    cmd: list[str], cwd: str | None = None, env: dict | None = None
+) -> tuple[int, str]:
     """Stream subprocess output to stdout and also capture it into a buffer."""
     import subprocess
     import threading
@@ -193,7 +268,7 @@ def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | No
         proc = subprocess.Popen(
             cmd,
             cwd=cwd,
-            env=env,
+            env=get_subprocess_env(env),
             stdout=subprocess.PIPE,
             stderr=subprocess.STDOUT,
             text=True,
@@ -207,8 +282,9 @@ def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | No
         try:
             for line in stdout:
                 line = line.rstrip()
-                print(line)
-                buf_lines.append(line)
+                if not should_filter_log_line(line):
+                    print(line)
+                    buf_lines.append(line)
         except Exception:
             pass
 
@@ -222,55 +298,6 @@ def _popen_stream_capture(cmd: list[str], cwd: str | None = None, env: dict | No
     return int(proc.returncode or 0), "\n".join(buf_lines)
 
 
-def _mask_secret_args(args: list[str]) -> list[str]:
-    masked: list[str] = []
-    for a in args:
-        if "=" in a and any(a.startswith(prefix) for prefix in ("ENVIRONMENT_API_KEY=", "OPENAI_API_KEY=", "SYNTH_API_KEY=")):
-            try:
-                key, value = a.split("=", 1)
-                tail = value[-5:] if len(value) >= 5 else value
-                masked.append(f"{key}=***{tail}")
-            except Exception:
-                masked.append("<masked>")
-        else:
-            masked.append(a)
-    return masked
-
-
-def _ensure_modal_secret(
-    secret_name: str,
-    *,
-    values: dict[str, str],
-    label: str = "deploy",
-    replace: bool = False,
-) -> bool:
-    prefix = f"[{label}]"
-    if not secret_name.strip():
-        raise RuntimeError("Secret name is required")
-
-    if not values:
-        raise RuntimeError("No values provided to create Modal secret")
-
-    create_args = [f"{k}={v}" for k, v in values.items()]
-    create_cmd = ["uv", "run", "modal", "secret", "create", secret_name, *create_args]
-
-    if replace:
-        print(f"{prefix} Removing Modal secret '{secret_name}' (if present)…")
-        delete_cmd = ["bash", "-lc", f"printf 'y\\n' | uv run modal secret delete {secret_name}"]
-        print(f"{prefix} Command:", " ".join(delete_cmd))
-        delete_code = _popen_stream(delete_cmd)
-        if delete_code != 0:
-            print(f"{prefix} Warning: delete command exited with {delete_code}; continuing to create")
-
-    print(f"\n{prefix} Creating Modal secret '{secret_name}'…")
-    print(f"{prefix} Command:", " ".join(_mask_secret_args(create_cmd)))
-    code = _popen_stream(create_cmd)
-    if code != 0:
-        raise RuntimeError("Failed to provision Modal secret (see logs above)")
-
-    return True
-
-
 def _fmt_float(value: float) -> str:
     return f"{value:.10g}"
 
@@ -283,11 +310,23 @@ def _find_asgi_apps(root: Path) -> list[Path]:
       - "@modal.asgi_app()"
     """
     results: list[Path] = []
-    skip_dirs = {".git", ".hg", ".svn", "node_modules", "dist", "build", "__pycache__", ".ruff_cache", ".mypy_cache", "venv", ".venv"}
+    skip_dirs = {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        "dist",
+        "build",
+        "__pycache__",
+        ".ruff_cache",
+        ".mypy_cache",
+        "venv",
+        ".venv",
+    }
     for dirpath, dirnames, filenames in os.walk(root):
         dirnames[:] = [d for d in dirnames if d not in skip_dirs]
         for name in filenames:
-            if not name.endswith(".py"):
+            if not str(name).endswith(".py"):
                 continue
             path = Path(dirpath) / name
             try:
@@ -297,16 +336,20 @@ def _find_asgi_apps(root: Path) -> list[Path]:
                     results.append(path)
             except Exception:
                 continue
+
     # Stable order: prioritize files under synth_demo/ first, then alphabetical
     def _priority(p: Path) -> tuple[int, str]:
         rel = str(p.resolve())
         in_demo = "/synth_demo/" in rel or rel.endswith("/synth_demo/task_app.py")
         return (0 if in_demo else 1, rel)
+
     results.sort(key=_priority)
     return results
 
 
-def _prompt_value(label: str, default: str | int | float, cast: Callable[[str], Any] | None = None) -> Any:
+def _prompt_value(
+    label: str, default: str | int | float, cast: Callable[[str], Any] | None = None
+) -> Any:
     prompt = f"{label} [{default}]: "
     try:
         raw = input(prompt).strip()
@@ -325,11 +368,23 @@ def _prompt_value(label: str, default: str | int | float, cast: Callable[[str],
 
 def _find_vllm_tomls(root: Path) -> list[Path]:
     results: list[Path] = []
-    skip_dirs = {".git", ".hg", ".svn", "node_modules", "dist", "build", "__pycache__", ".ruff_cache", ".mypy_cache", "venv", ".venv"}
+    skip_dirs = {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        "dist",
+        "build",
+        "__pycache__",
+        ".ruff_cache",
+        ".mypy_cache",
+        "venv",
+        ".venv",
+    }
     for dirpath, dirnames, filenames in os.walk(root):
         dirnames[:] = [d for d in dirnames if d not in skip_dirs]
         for name in filenames:
-            if not name.endswith(".toml"):
+            if not str(name).endswith(".toml"):
                 continue
             path = Path(dirpath) / name
             try:
@@ -345,7 +400,9 @@ def _create_new_config(env: DemoEnv) -> str:
     default_path = os.path.join(os.getcwd(), "demo_config.toml")
     while True:
         try:
-            destination = input(f"Path to save new config [{default_path}]: ").strip() or default_path
+            destination = (
+                input(f"Path to save new config [{default_path}]: ").strip() or default_path
+            )
         except Exception:
             destination = default_path
         destination = os.path.abspath(destination)
@@ -354,7 +411,9 @@ def _create_new_config(env: DemoEnv) -> str:
             continue
         if os.path.exists(destination):
             try:
-                overwrite = input(f"{destination} exists. Overwrite? [y/N]: ").strip().lower() or "n"
+                overwrite = (
+                    input(f"{destination} exists. Overwrite? [y/N]: ").strip().lower() or "n"
+                )
             except Exception:
                 overwrite = "n"
             if not overwrite.startswith("y"):
@@ -366,7 +425,9 @@ def _create_new_config(env: DemoEnv) -> str:
     model_name = _prompt_value("Model name", "Qwen/Qwen3-0.6B")
     compute_gpu_type = _prompt_value("Compute GPU type", "H100")
     compute_gpu_count = _prompt_value("Compute GPU count", 4, int)
-    topology_gpu_type = _prompt_value("Topology GPU type", f"{compute_gpu_type}:{compute_gpu_count}")
+    topology_gpu_type = _prompt_value(
+        "Topology GPU type", f"{compute_gpu_type}:{compute_gpu_count}"
+    )
     gpus_for_vllm = _prompt_value("Topology gpus_for_vllm", 2, int)
     gpus_for_training = _prompt_value("Topology gpus_for_training", 1, int)
     tensor_parallel = _prompt_value("Topology tensor_parallel", 2, int)
@@ -384,8 +445,9 @@ def _create_new_config(env: DemoEnv) -> str:
     task_url_default = env.task_app_base_url or ""
     services_task_url = _prompt_value("services.task_url", task_url_default)
 
-    template = textwrap.dedent(
-        f"""\
+    template = (
+        textwrap.dedent(
+            f"""\
         # Crafter online RL training configuration (research local copy)
 
         [model]
@@ -527,7 +589,9 @@ def _create_new_config(env: DemoEnv) -> str:
         [services]
         task_url = \"{services_task_url}\"
         """
-    ).strip() + "\n"
+        ).strip()
+        + "\n"
+    )
 
     with open(destination, "w", encoding="utf-8") as fh:
         fh.write(template)
@@ -546,7 +610,11 @@ def _select_or_create_config(explicit: str | None, env: DemoEnv) -> str:
     discovered = _find_vllm_tomls(search_root)
 
     extras: list[Path] = []
-    packaged = Path(os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "demo_task_apps", "math", "config.toml")))
+    packaged = Path(
+        os.path.abspath(
+            os.path.join(os.path.dirname(__file__), "..", "demo_task_apps", "math", "config.toml")
+        )
+    )
     extras.append(packaged)
     home_cfg = Path(os.path.expanduser("~/.synth-ai/demo_config.toml"))
     extras.append(home_cfg)
@@ -592,29 +660,36 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
 
     env_key = (env.env_api_key or "").strip()
     if not env_key:
-        raise RuntimeError(f"[{label}] ENVIRONMENT_API_KEY missing. Run `uvx synth-ai rl_demo deploy` first.")
+        raise RuntimeError(
+            f"[{label}] ENVIRONMENT_API_KEY missing. Run `uvx synth-ai rl_demo deploy` first."
+        )
 
     task_url = env.task_app_base_url
     if not task_url or not _is_modal_public_url(task_url):
         resolved = ""
         if env.task_app_name:
             try:
-                choice = input(
-                    f"Resolve URL from Modal for app '{env.task_app_name}'? [Y/n]: "
-                ).strip().lower() or "y"
+                choice = (
+                    input(f"Resolve URL from Modal for app '{env.task_app_name}'? [Y/n]: ")
+                    .strip()
+                    .lower()
+                    or "y"
+                )
             except Exception:
                 choice = "y"
             if choice.startswith("y"):
-                code, out = _popen_capture([
-                    "uv",
-                    "run",
-                    "python",
-                    "-m",
-                    "modal",
-                    "app",
-                    "url",
-                    env.task_app_name,
-                ])
+                code, out = _popen_capture(
+                    [
+                        "uv",
+                        "run",
+                        "python",
+                        "-m",
+                        "modal",
+                        "app",
+                        "url",
+                        env.task_app_name,
+                    ]
+                )
                 if code == 0 and out:
                     for tok in out.split():
                         if _is_modal_public_url(tok):
@@ -623,7 +698,9 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
         if not resolved:
             print(f"[{label}] Task app URL not configured or not a valid Modal public URL.")
             print("Examples: https://<app-name>-fastapi-app.modal.run")
-            entered = input("Enter Task App base URL (must contain '.modal.run'), or press Enter to abort: ").strip()
+            entered = input(
+                "Enter Task App base URL (must contain '.modal.run'), or press Enter to abort: "
+            ).strip()
             if not entered or not _is_modal_public_url(entered):
                 raise RuntimeError(f"[{label}] Valid Task App URL is required.")
             task_url = entered.rstrip("/")
@@ -639,30 +716,26 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
         app_name = fallback
         demo_core.persist_task_url(task_url, name=app_name)
 
-    secret_name = env.task_app_secret_name.strip() or f"{app_name}-secret"
     demo_core.persist_task_url(task_url, name=app_name)
-    demo_core.persist_dotenv_values({
-        "TASK_APP_BASE_URL": task_url,
-        "TASK_APP_NAME": app_name,
-        "TASK_APP_SECRET_NAME": secret_name,
-    })
-
-    openai_key = (os.environ.get("OPENAI_API_KEY") or local_env.get("OPENAI_API_KEY") or "").strip()
-    secret_values: dict[str, str] = {"ENVIRONMENT_API_KEY": env_key}
-    if openai_key:
-        secret_values["OPENAI_API_KEY"] = openai_key
+    demo_core.persist_dotenv_values(
+        {
+            "TASK_APP_BASE_URL": task_url,
+            "TASK_APP_NAME": app_name,
+            "TASK_APP_SECRET_NAME": DEFAULT_TASK_APP_SECRET_NAME,
+        }
+    )
+
     if synth_key:
-        secret_values["SYNTH_API_KEY"] = synth_key
+        os.environ["SYNTH_API_KEY"] = synth_key
 
-    _ensure_modal_secret(secret_name, values=secret_values, label=label, replace=True)
+    openai_key = (os.environ.get("OPENAI_API_KEY") or local_env.get("OPENAI_API_KEY") or "").strip()  # type: ignore[misc]
+    if openai_key:
+        os.environ["OPENAI_API_KEY"] = openai_key
 
-    rollout_url = task_url.rstrip("/") + "/health/rollout"
     print(f"[{label}] Verifying rollout health:")
     try:
         ek = (env_key or "").strip()
-        ek_len = len(ek)
-        ek_tail = ek[-5:] if ek_len >= 5 else ek
-        print(f"[{label}] Using ENVIRONMENT_API_KEY len={ek_len} last5={ek_tail}")
+        print(f"[{label}] {_key_preview(ek, 'ENVIRONMENT_API_KEY')}")
     except Exception:
         pass
     health_base = task_url.rstrip("/")
@@ -673,7 +746,6 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
         print(f"[{label}] GET", h)
         rc, body = _http("GET", h, headers={"X-API-Key": env_key})
         if rc == 200:
-            rollout_url = h
             break
     print(f"[{label}] status: {rc}")
     try:
@@ -685,41 +757,64 @@ def _ensure_task_app_ready(env: DemoEnv, synth_key: str, *, label: str) -> DemoE
     print(f"[{label}] body:", preview)
     if rc != 200:
         print(f"[{label}] Warning: rollout health check failed ({rc}). Response: {body}")
+        with contextlib.suppress(Exception):
+            print(f"[{label}] Sent header X-API-Key → {_key_preview(env_key, 'X-API-Key')}")
     else:
         print(f"[{label}] Task app rollout health check OK.")
 
     os.environ["TASK_APP_BASE_URL"] = task_url
     os.environ["ENVIRONMENT_API_KEY"] = env_key
+    os.environ["TASK_APP_SECRET_NAME"] = DEFAULT_TASK_APP_SECRET_NAME
     updated_env = demo_core.load_env()
     updated_env.env_api_key = env_key
     updated_env.task_app_base_url = task_url
     updated_env.task_app_name = app_name
-    updated_env.task_app_secret_name = secret_name
+    updated_env.task_app_secret_name = DEFAULT_TASK_APP_SECRET_NAME
     return updated_env
 
 
-def cmd_deploy(args: argparse.Namespace) -> int:
+def deploy(
+    local: bool = False, app: str | None = None, name: str | None = None, script: str | None = None
+) -> int:
+    # Change to demo directory if stored
+    demo_dir = demo_core.load_demo_dir()
+    if demo_dir and os.path.isdir(demo_dir):
+        os.chdir(demo_dir)
+        print(f"Using demo directory: {demo_dir}")
+
     env = demo_core.load_env()
+    os.environ["TASK_APP_SECRET_NAME"] = DEFAULT_TASK_APP_SECRET_NAME
     cwd_env_path = os.path.join(os.getcwd(), ".env")
     local_env = demo_core.load_dotenv_file(cwd_env_path)
     url = ""
     app_name = env.task_app_name or ""
     try:
-        if args.local:
+        if local:
             print("Starting local Task App…")
             import subprocess
-            subprocess.Popen([sys.executable, "-c", "from synth_ai.demos.demo_task_apps.math.app import run; run()"],
-                             stdout=sys.stdout, stderr=sys.stderr)
+
+            subprocess.Popen(
+                [
+                    sys.executable,
+                    "-c",
+                    "from synth_ai.cli.demo_apps.demo_task_apps.math.app import run; run()",
+                ],
+                env=get_subprocess_env(),
+                stdout=sys.stdout,
+                stderr=sys.stderr,
+            )
             target = "http://127.0.0.1:8080"
             app_name = ""
             for _ in range(30):
-                if demo_core.assert_http_ok(target + "/health", method="GET") or demo_core.assert_http_ok(target, method="GET"):
+                if demo_core.assert_http_ok(
+                    target + "/health", method="GET"
+                ) or demo_core.assert_http_ok(target, method="GET"):
                     url = target
                     break
                 time.sleep(1)
         else:
             # Auto-detect app path if not supplied; prompt interactively from discovered ASGI apps
-            app_path = os.path.abspath(args.app) if args.app else None
+            app_path = os.path.abspath(app) if app else None
             if not app_path or not os.path.isfile(app_path):
                 # First pass: look for known common filenames
                 candidates = [
@@ -738,7 +833,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                             rel = os.path.relpath(str(pth), os.getcwd())
                             print(f"  [{idx}] {rel}")
                         try:
-                            sel = input(f"Enter choice [1-{len(found)}] (default 1): ").strip() or "1"
+                            sel = (
+                                input(f"Enter choice [1-{len(found)}] (default 1): ").strip() or "1"
+                            )
                         except Exception:
                             sel = "1"
                         try:
@@ -747,12 +844,15 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                             choice = 1
                         choice = max(1, min(choice, len(found)))
                         app_path = str(found[choice - 1].resolve())
-            if not app_path and args.script:
+            if not app_path and script:
                 # Legacy script fallback if user supplied --script explicitly
-                from synth_ai.demos.demo_task_apps.math.deploy_modal import deploy as modal_deploy
-                url = modal_deploy(script_path=args.script, env_api_key=env.env_api_key)
-                if args.name:
-                    app_name = args.name
+                from synth_ai.cli.demo_apps.demo_task_apps.math.deploy_modal import (
+                    deploy as modal_deploy,
+                )
+
+                url = modal_deploy(script_path=script, env_api_key=env.env_api_key)
+                if name:
+                    app_name = name
             else:
                 if not app_path:
                     entered = input("Path to Modal app.py (e.g., ./task_app.py): ").strip()
@@ -763,7 +863,10 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     raise FileNotFoundError(f"App file not found: {app_path}")
                 # Surface the app path before asking for the name
                 print(f"Using task app: {app_path}")
-                suggested_name = args.name or f"synth-{os.path.splitext(os.path.basename(app_path))[0]}"
+                existing_name = (name or env.task_app_name or "").strip()
+                if not existing_name:
+                    existing_name = f"synth-{os.path.splitext(os.path.basename(app_path))[0]}"
+                suggested_name = existing_name
                 name_in = input(f"Modal app name [{suggested_name}]: ").strip() or suggested_name
                 app_name = name_in
                 print("\nAbout to deploy with:")
@@ -774,21 +877,23 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     print("Aborted by user.")
                     return 1
 
-                secret_name = (env.task_app_secret_name or "").strip() or f"{name_in}-secret"
                 existing_env_key = (env.env_api_key or "").strip()
                 env_key: str | None = existing_env_key or None
                 if existing_env_key:
                     try:
-                        reuse_choice = input(
-                            "Use existing ENVIRONMENT_API_KEY from state/.env? [Y/n]: "
-                        ).strip().lower() or "y"
+                        reuse_choice = (
+                            input("Use existing ENVIRONMENT_API_KEY from state/.env? [Y/n]: ")
+                            .strip()
+                            .lower()
+                            or "y"
+                        )
                     except Exception:
                         reuse_choice = "y"
                     if not reuse_choice.startswith("y"):
                         env_key = None
 
                 if env_key is None:
-                    from synth_ai.rl.secrets import mint_environment_api_key
+                    from synth_ai.sdk.learning.rl.secrets import mint_environment_api_key
 
                     env_key = mint_environment_api_key()
                     demo_core.persist_env_api_key(env_key)
@@ -797,69 +902,90 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     env.env_api_key = env_key
                     local_env["ENVIRONMENT_API_KEY"] = env_key
                     print("[deploy] Minted new ENVIRONMENT_API_KEY")
-                
+                elif env_key:
+                    os.environ["ENVIRONMENT_API_KEY"] = env_key
+
                 # Optionally upload the new key to the backend using sealed box helper
-                backend_base = env.dev_backend_url or ""
-                synth_key = (env.synth_api_key or os.environ.get("SYNTH_API_KEY") or local_env.get("SYNTH_API_KEY") or "").strip()
+                backend_base = (env.dev_backend_url or "").rstrip("/")
+                synth_key = (
+                    env.synth_api_key
+                    or os.environ.get("SYNTH_API_KEY")  # type: ignore[misc]
+                    or local_env.get("SYNTH_API_KEY")  # type: ignore[misc]
+                    or ""
+                ).strip()
                 if backend_base and synth_key:
-                        backend_base = backend_base.rstrip("/")
-                        if not backend_base.endswith("/api"):
-                            backend_base = f"{backend_base}/api"
+                    # Pass a base WITHOUT trailing /api to setup_environment_api_key,
+                    # since it appends /api/v1/... internally.
+                    non_api_base = (
+                        backend_base[:-4] if backend_base.endswith("/api") else backend_base
+                    )
+                    try:
+                        choice = (
+                            input(f"Upload ENVIRONMENT_API_KEY to backend {non_api_base}? [Y/n]: ")
+                            .strip()
+                            .lower()
+                            or "y"
+                        )
+                    except Exception:
+                        choice = "y"
+                    if choice.startswith("y"):
                         try:
-                            choice = input(
-                                f"Upload ENVIRONMENT_API_KEY to backend {backend_base}? [Y/n]: "
-                            ).strip().lower() or "y"
-                        except Exception:
-                            choice = "y"
-                        if choice.startswith("y"):
-                            try:
-                                print(f"[deploy] Uploading ENVIRONMENT_API_KEY to {backend_base} …")
-                                from synth_ai.rl.env_keys import setup_environment_api_key
-
-                                setup_environment_api_key(backend_base.rstrip("/"), synth_key, token=env_key)
-                                print("[deploy] Backend sealed-box upload complete.")
-                            except Exception as upload_err:
-                                print(f"[deploy] Failed to upload ENVIRONMENT_API_KEY: {upload_err}")
-                                print(
-                                    "Hint: run `uvx python -c \"from synth_ai.rl.env_keys import setup_environment_api_key as s;"
-                                    " s('<backend>', '<synth_api_key>')\"` once the backend is reachable."
-                                )
-
-                synth_key = (env.synth_api_key or os.environ.get("SYNTH_API_KEY") or local_env.get("SYNTH_API_KEY") or "").strip()
+                            print(f"[deploy] Uploading ENVIRONMENT_API_KEY to {non_api_base} …")
+                            from synth_ai.sdk.learning.rl.env_keys import setup_environment_api_key
+
+                            setup_environment_api_key(non_api_base, synth_key, token=env_key)
+                            print("[deploy] Backend sealed-box upload complete.")
+                        except Exception as upload_err:
+                            print(f"[deploy] Failed to upload ENVIRONMENT_API_KEY: {upload_err}")
+                            print(
+                                'Hint: run `uvx python -c "from synth_ai.sdk.learning.rl.env_keys import setup_environment_api_key as s;'
+                                " s('<backend>', '<synth_api_key>')\"` once the backend is reachable."
+                            )
+
+                synth_key = (
+                    env.synth_api_key
+                    or os.environ.get("SYNTH_API_KEY")  # type: ignore[misc]
+                    or local_env.get("SYNTH_API_KEY")  # type: ignore[misc]
+                    or ""
+                ).strip()
                 if not synth_key:
-                    synth_key = input("Enter SYNTH_API_KEY for Modal secret (required): ").strip()
+                    synth_key = input("Enter SYNTH_API_KEY for deployment (required): ").strip()
                     if not synth_key:
-                        print("SYNTH_API_KEY is required to create the Modal secret.")
+                        print("SYNTH_API_KEY is required for deployment.")
                         return 1
                     demo_core.persist_api_key(synth_key)
                     demo_core.persist_dotenv_values({"SYNTH_API_KEY": synth_key})
                     env.synth_api_key = synth_key
+                os.environ["SYNTH_API_KEY"] = synth_key
 
-                openai_key = (os.environ.get("OPENAI_API_KEY") or local_env.get("OPENAI_API_KEY") or "").strip()
+                openai_key = (
+                    os.environ.get("OPENAI_API_KEY") or local_env.get("OPENAI_API_KEY") or ""
+                ).strip()
                 if not openai_key:
                     openai_key = input(
                         "Enter your OpenAI API key, found at https://platform.openai.com/api-keys\n> "
                     ).strip()
                     if not openai_key:
-                        print("OPENAI_API_KEY is required to create the Modal secret.")
+                        print("OPENAI_API_KEY is required for deployment.")
                         return 1
                     demo_core.persist_dotenv_values({"OPENAI_API_KEY": openai_key})
                     local_env["OPENAI_API_KEY"] = openai_key
+                os.environ["OPENAI_API_KEY"] = openai_key
 
-                values = {"SYNTH_API_KEY": synth_key, "OPENAI_API_KEY": openai_key}
-                if env_key:
-                    values["ENVIRONMENT_API_KEY"] = env_key
-
-                try:
-                    created = _ensure_modal_secret(secret_name, values=values, label="deploy", replace=True)
-                except RuntimeError as secret_err:
-                    print(f"Failed to prepare Modal secret '{secret_name}': {secret_err}")
-                    return 2
-                if created:
-                    print(f"[deploy] Modal secret '{secret_name}' provisioned.")
-
-                deploy_cmd = ["uv", "run", "python", "-m", "modal", "deploy", "--name", name_in, app_path]
-                print("\nStreaming Modal build/deploy logs (this can take several minutes on first run)…\n")
+                deploy_cmd = [
+                    "uv",
+                    "run",
+                    "python",
+                    "-m",
+                    "modal",
+                    "deploy",
+                    "--name",
+                    name_in,
+                    app_path,
+                ]
+                print(
+                    "\nStreaming Modal build/deploy logs (this can take several minutes on first run)…\n"
+                )
                 code, deploy_logs = _popen_stream_capture(deploy_cmd)
                 if code != 0:
                     raise RuntimeError(f"modal deploy failed (exit {code})")
@@ -867,6 +993,7 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                 if not url:
                     try:
                         import re as _re
+
                         m_all = _re.findall(r"https?://[^\s]+\.modal\.run", deploy_logs or "")
                         if m_all:
                             url = m_all[-1].strip().rstrip("/")
@@ -881,7 +1008,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                             break
                 # Fallback: try reading recent Modal logs for the app to find a URL line
                 if not url:
-                    code3, out3 = _popen_capture(["uv", "run", "python", "-m", "modal", "app", "list"])
+                    code3, out3 = _popen_capture(
+                        ["uv", "run", "python", "-m", "modal", "app", "list"]
+                    )
                     if code3 == 0 and out3:
                         for line in out3.splitlines():
                             if name_in in line:
@@ -894,7 +1023,9 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                 # Prompt user if still no valid URL
                 if not url:
                     print("\nCould not auto-detect a public Modal URL for the app.")
-                    entered = input("Enter the Modal public URL (must contain '.modal.run'), or press Enter to abort: ").strip()
+                    entered = input(
+                        "Enter the Modal public URL (must contain '.modal.run'), or press Enter to abort: "
+                    ).strip()
                     if entered and _is_modal_public_url(entered):
                         url = entered.rstrip("/")
                 if not url:
@@ -906,7 +1037,7 @@ def cmd_deploy(args: argparse.Namespace) -> int:
         dotenv_values = {"TASK_APP_BASE_URL": url}
         if app_name:
             dotenv_values["TASK_APP_NAME"] = app_name
-            dotenv_values["TASK_APP_SECRET_NAME"] = f"{app_name}-secret"
+        dotenv_values["TASK_APP_SECRET_NAME"] = DEFAULT_TASK_APP_SECRET_NAME
         dotenv_path = demo_core.persist_dotenv_values(dotenv_values)
         print(f"TASK_APP_BASE_URL={url}")
         if app_name:
@@ -915,16 +1046,16 @@ def cmd_deploy(args: argparse.Namespace) -> int:
         print(f"  export TASK_APP_BASE_URL={url}")
         if app_name:
             print(f"  export TASK_APP_NAME={app_name}")
-            print(f"  export TASK_APP_SECRET_NAME={app_name}-secret")
         print(f"Persisted to {dotenv_path}")
-        print("Next: uvx synth-ai run")
+        print("\nNext step:\n$ uvx synth-ai run")
         return 0
     except Exception as e:
         print(f"Deploy error: {e}")
         return 2
 
-
-    print("`rl_demo configure` prepares environment and secrets; `synth-ai run` now handles launches.")
+    print(
+        "`rl_demo configure` prepares environment and secrets; `synth-ai run` now handles launches."
+    )
     env = demo_core.load_env()
     synth_key = (env.synth_api_key or "").strip()
     if not synth_key:
@@ -956,133 +1087,314 @@ def cmd_deploy(args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_init(args: argparse.Namespace) -> int:
-    """Initialize a Modal-ready Math Task App in the current directory.
+def _ensure_modal_installed() -> None:
+    """Install the modal package if it is not already available and check authentication."""
 
-    Copies `examples/rl/task_app.py` and `examples/rl/deploy_task_app.sh` into CWD.
-    Creates a `.env` with placeholders if it does not exist.
-    """
+    # Check if modal is installed
+    modal_installed = False
     try:
-        # Ensure `modal` is installed for deployment flows
-        def _has_modal() -> bool:
-            try:
-                import importlib.util as _iu
-                return _iu.find_spec("modal") is not None
-            except Exception:
-                return False
+        import importlib.util as _iu
 
-        if not _has_modal():
-            print("modal not found; installing…")
-            # Prefer uv if available; otherwise fallback to pip
-            try:
-                if shutil.which("uv"):
-                    code, out = _popen_capture(["uv", "pip", "install", "modal>=1.1.4"])
-                else:
-                    code, out = _popen_capture([sys.executable, "-m", "pip", "install", "modal>=1.1.4"])
-                if code != 0:
-                    print(out)
-                    print("Failed to install modal; continuing may fail.")
-                else:
-                    print("modal installed successfully.")
-            except Exception as e:
-                print(f"modal install error: {e}")
-            # Re-check
-            if not _has_modal():
-                print("Warning: modal is still not importable after install attempt.")
-        else:
-            print("modal found")
-
-        here = os.getcwd()
-        demo_dir = os.path.join(here, "synth_demo")
-        os.makedirs(demo_dir, exist_ok=True)
-        # Paths inside synth_demo/
-        dst_task_py = os.path.join(demo_dir, "task_app.py")
-        dst_deploy = os.path.join(demo_dir, "deploy_task_app.sh")
-        env_path = os.path.join(demo_dir, ".env")
-        dst_cfg = os.path.join(demo_dir, "demo_config.toml")
-
-        # Copy packaged math modal task app into synth_demo/task_app.py
-        src_modal = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "demo_task_apps", "math", "modal_task_app.py"))
-        if not os.path.isfile(src_modal):
-            print("Init failed: packaged math modal task app not found.")
-            print(f"Looked for: {src_modal}")
-            return 1
-        if os.path.exists(dst_task_py) and not getattr(args, "force", False):
-            print(f"Refusing to overwrite existing file: {dst_task_py} (use --force)")
-            return 1
-        shutil.copy2(src_modal, dst_task_py)
-
-        # Create deploy script in synth_demo/
-        deploy_text = r"""#!/usr/bin/env bash
-set -euo pipefail
-
-HERE=$(cd "$(dirname "$0")" && pwd)
-APP="$HERE/task_app.py"
-if [ -f "$HERE/.env" ]; then
-  # shellcheck disable=SC2046
-  export $(grep -v '^#' "$HERE/.env" | xargs -I{} echo {})
-fi
-uv run modal deploy "$APP" | tee "$HERE/.last_deploy.log"
-URL=$(grep -Eo 'https://[^ ]+\.modal\.run' "$HERE/.last_deploy.log" | tail -1 || true)
-if [ -n "$URL" ]; then
-  if grep -q '^TASK_APP_BASE_URL=' "$HERE/.env" 2>/dev/null; then
-    sed -i.bak "s#^TASK_APP_BASE_URL=.*#TASK_APP_BASE_URL=$URL#" "$HERE/.env" || true
-  else
-    echo "TASK_APP_BASE_URL=$URL" >> "$HERE/.env"
-  fi
-  echo "Saved TASK_APP_BASE_URL to $HERE/.env"
-fi
-"""
-        _write_text(dst_deploy, deploy_text)
+        if _iu.find_spec("modal") is not None:
+            modal_installed = True
+    except Exception:
+        pass
+
+    # Install modal if needed
+    if not modal_installed:
+        print("modal not found; installing…")
+        try:
+            if shutil.which("uv"):
+                code, out = _popen_capture(["uv", "pip", "install", "modal>=1.1.4"])
+            else:
+                code, out = _popen_capture([sys.executable, "-m", "pip", "install", "modal>=1.1.4"])
+            if code != 0:
+                print(out)
+                print("Failed to install modal; continuing may fail.")
+                return
+            else:
+                print("✓ modal installed successfully")
+                modal_installed = True
+        except Exception as exc:
+            print(f"modal install error: {exc}")
+            return
+
+    # Verify modal is importable
+    if modal_installed:
         try:
-            st = os.stat(dst_deploy)
-            os.chmod(dst_deploy, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+            import importlib.util as _iu
+
+            if _iu.find_spec("modal") is None:
+                print("Warning: modal is still not importable after install attempt.")
+                return
         except Exception:
-            pass
+            print("Warning: unable to verify modal installation.")
+            return
+
+    # Check modal authentication status
+    auth_ok, auth_msg = demo_core.modal_auth_status()
+    if auth_ok:
+        print(f"✓ Modal authenticated: {auth_msg}")
+    else:
+        print("\n⚠️  Modal authentication required")
+        print(f"   Status: {auth_msg}")
+        print("\n   To authenticate Modal, run:")
+        print("     modal setup")
+        print("\n   Or set environment variables:")
+        print("     export MODAL_TOKEN_ID=your-token-id")
+        print("     export MODAL_TOKEN_SECRET=your-token-secret")
+        print("\n   You can deploy later after authenticating.\n")
+
+
+def init(template: str | None = None, dest: str | None = None, force: bool = False) -> int:
+    """Materialise a demo task app template into the current directory."""
+
+    templates = list(list_demo_templates())
+    if not templates:
+        print("No demo templates registered. Update synth_ai/demo_registry.py to add entries.")
+        return 1
+
+    selected: DemoTemplate | None = None
+    if template:
+        selected = get_demo_template(template)
+        if selected is None:
+            available = ", ".join(t.template_id for t in templates)
+            print(f"Unknown template '{template}'. Available: {available}")
+            return 1
+    else:
+        if force:
+            selected = templates[0]
+            print(
+                f"Using default template: {selected.name} ({selected.template_id}) "
+                f"(pass --template to choose another)"
+            )
+        else:
+            print("Select a demo template:" + "\n")
+            for idx, tpl in enumerate(templates, start=1):
+                print(f"  [{idx}] {tpl.name} ({tpl.template_id})")
+                print(f"      {tpl.description}")
+            try:
+                choice_raw = input(f"Enter choice [1-{len(templates)}] (default 1): ").strip() or "1"
+            except Exception:
+                choice_raw = "1"
+            if not choice_raw.isdigit():
+                print("Selection must be a number.")
+                return 1
+            choice_idx = int(choice_raw)
+            if not 1 <= choice_idx <= len(templates):
+                print("Selection out of range.")
+                return 1
+            selected = templates[choice_idx - 1]
+
+    assert selected is not None
+
+    default_subdir = selected.default_subdir or selected.template_id
+
+    # Check if default destination is already occupied and switch to local_demos/ if needed
+    if dest:
+        default_dest = Path(dest).expanduser().resolve()
+    else:
+        primary_dest = Path.cwd() / default_subdir
+        if primary_dest.exists() and any(primary_dest.iterdir()):
+            # Switch to local_demos/ automatically if primary location is occupied
+            default_dest = (Path.cwd() / "local_demos" / default_subdir).resolve()
+        else:
+            default_dest = primary_dest.resolve()
 
-        # Seed .env if not present
-        if not os.path.exists(env_path):
-            _write_text(env_path, "\n".join([
-                "# Required for task app auth to environment service",
-                "ENVIRONMENT_API_KEY=",
-                "",
-                "# Optional: for CLI job submission and proxying OpenAI models",
-                "SYNTH_API_KEY=",
-                "OPENAI_API_KEY=",
-                "",
-                "# Optional: set to 'prod' to use production names",
-                "ENVIRONMENT=",
-            ]) + "\n")
-
-        # Seed demo_config.toml from packaged default if not present (or overwrite with --force)
-        packaged_cfg = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "demo_task_apps", "math", "config.toml"))
+    if force:
+        dest_input = ""
+    else:
         try:
-            if os.path.isfile(packaged_cfg):
-                if not os.path.exists(dst_cfg) or getattr(args, "force", False):
-                    shutil.copy2(packaged_cfg, dst_cfg)
+            dest_input = input(f"Destination directory [{default_dest}]: ").strip()
         except Exception:
-            pass
+            dest_input = ""
+    destination = Path(dest_input).expanduser().resolve() if dest_input else default_dest
+
+    # Track whether we should skip individual file prompts (if we already cleared the directory)
+    directory_cleared = False
+
+    if destination.exists():
+        if destination.is_file():
+            print(f"Destination {destination} is a file. Provide a directory path.")
+            return 1
+        if any(destination.iterdir()):
+            if force:
+                response = "y"
+            else:
+                try:
+                    response = (
+                        input(f"Destination {destination} is not empty. Overwrite? [y/N]: ")
+                        .strip()
+                        .lower()
+                    )
+                except (EOFError, KeyboardInterrupt):
+                    print("\nCancelled.")
+                    return 1
+            if response not in ("y", "yes"):
+                print("Cancelled. Choose another directory or delete the existing one.")
+                return 1
+            # User agreed to overwrite - clear the entire directory including hidden files
+            print(f"Clearing {destination}...")
+            try:
+                # Remove all contents including hidden files (.env, .git, etc.)
+                shutil.rmtree(destination)
+            except Exception as e:
+                print(f"Error clearing directory: {e}")
+                print("Please manually remove the directory and try again.")
+                return 1
+            # Recreate empty directory
+            destination.mkdir(parents=True, exist_ok=True)
+            # Verify it's actually empty
+            if any(destination.iterdir()):
+                print(f"Warning: Directory {destination} still contains files after clearing.")
+                print("Some files may not have been removed. Please check manually.")
+                return 1
+            directory_cleared = True
+    else:
+        destination.mkdir(parents=True, exist_ok=True)
+
+    if selected.requires_modal:
+        _ensure_modal_installed()
+
+    try:
+        for spec in selected.iter_copy_specs():
+            src_path = spec.absolute_source()
+            if not src_path.exists():
+                print(f"Template source missing: {src_path}")
+                return 1
+            dest_path = (destination / spec.destination).resolve()
+
+            # Handle directory copying
+            if src_path.is_dir():
+                if dest_path.exists() and not directory_cleared:
+                    if force:
+                        response = "y"
+                    else:
+                        try:
+                            response = (
+                                input(f"Directory {dest_path.name} exists. Overwrite? [y/N]: ")
+                                .strip()
+                                .lower()
+                            )
+                        except (EOFError, KeyboardInterrupt):
+                            print("\nCancelled.")
+                            return 1
+                    if response not in ("y", "yes"):
+                        print(f"Skipping {dest_path.name}")
+                        continue
+                    shutil.rmtree(dest_path)
+                elif dest_path.exists() and directory_cleared:
+                    shutil.rmtree(dest_path)
+                shutil.copytree(src_path, dest_path)
+            else:
+                # Handle file copying
+                dest_path.parent.mkdir(parents=True, exist_ok=True)
+                if dest_path.exists() and not directory_cleared:
+                    if force:
+                        response = "y"
+                    else:
+                        try:
+                            response = (
+                                input(f"File {dest_path.name} exists. Overwrite? [y/N]: ")
+                                .strip()
+                                .lower()
+                            )
+                        except (EOFError, KeyboardInterrupt):
+                            print("\nCancelled.")
+                            return 1
+                    if response not in ("y", "yes"):
+                        print(f"Skipping {dest_path.name}")
+                        continue
+                shutil.copy2(src_path, dest_path)
+                if spec.make_executable:
+                    try:
+                        st = os.stat(dest_path)
+                        os.chmod(dest_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+                    except Exception:
+                        pass
 
-        print("Initialized Math Task App in synth_demo/:")
-        print(f"  - {dst_task_py}")
-        print(f"  - {dst_deploy}")
-        print(f"  - {env_path} (created if missing)")
-        if os.path.exists(dst_cfg):
-            print(f"  - {dst_cfg} (seeded)")
-        print("")
-        print("Next steps:")
-        print("  1) cd synth_demo && put your ENVIRONMENT_API_KEY in ./.env")
-        print("  2) Deploy to Modal:")
-        print("     uvx bash ./deploy_task_app.sh")
-        print("  3) From project root, run: uvx synth-ai run")
+        if selected.env_lines:
+            env_path = destination / ".env"
+            should_write = True
+            if env_path.exists() and not directory_cleared:
+                if force:
+                    response = "y"
+                else:
+                    try:
+                        response = input("File .env exists. Overwrite? [y/N]: ").strip().lower()
+                    except (EOFError, KeyboardInterrupt):
+                        print("\nCancelled.")
+                        return 1
+                should_write = response in ("y", "yes")
+            if should_write:
+                _write_text(str(env_path), "\n".join(selected.env_lines) + "\n")
+            elif not directory_cleared:
+                print("Skipping .env")
+
+        config_src = selected.config_source_path()
+        if config_src and config_src.exists():
+            cfg_dst = (destination / selected.config_destination).resolve()
+            should_copy = True
+            if cfg_dst.exists() and not directory_cleared:
+                if force:
+                    response = "y"
+                else:
+                    try:
+                        response = (
+                            input(f"File {cfg_dst.name} exists. Overwrite? [y/N]: ").strip().lower()
+                        )
+                    except (EOFError, KeyboardInterrupt):
+                        print("\nCancelled.")
+                        return 1
+                should_copy = response in ("y", "yes")
+            if should_copy:
+                cfg_dst.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(config_src, cfg_dst)
+            elif not directory_cleared:
+                print(f"Skipping {cfg_dst.name}")
+
+        if selected.post_copy is not None:
+            try:
+                selected.post_copy(destination)
+            except Exception as post_exc:
+                print(f"Post-processing failed: {post_exc}")
+                return 1
+
+        # Store demo directory for subsequent commands
+        demo_core.persist_demo_dir(str(destination))
+
+        # Store .env path if it was created
+        env_file = destination / ".env"
+        if env_file.exists():
+            demo_core.persist_env_file_path(str(env_file))
+
+        print(f"Demo template '{selected.name}' materialised at {destination}.")
+        print("Files created:")
+        for spec in selected.iter_copy_specs():
+            print(f"  - {spec.destination}")
+        if selected.env_lines:
+            print("  - .env")
+        if selected.config_source_path():
+            print(f"  - {selected.config_destination}")
+        print("\nDemo directory stored. Subsequent commands will use this directory automatically.")
+        print("Review the files, edit .env, and run any provided deploy scripts when ready.")
         return 0
-    except Exception as e:
-        print(f"Init error: {e}")
-        return 2
+    except KeyboardInterrupt:
+        print("Aborted")
+        return 1
+    except Exception as exc:
+        print(f"Init failed: {exc}")
+        return 1
+
 
+def _http(
+    method: str, url: str, headers: dict[str, str] | None = None, body: dict[str, Any] | None = None
+) -> tuple[int, dict[str, Any] | str]:
+    import json as _json
+    import ssl
+    import urllib.error
+    import urllib.request
 
-def _http(method: str, url: str, headers: Dict[str, str] | None = None, body: Dict[str, Any] | None = None) -> tuple[int, Dict[str, Any] | str]:
-    import urllib.request, urllib.error, json as _json, ssl
     data = None
     if body is not None:
         data = _json.dumps(body).encode("utf-8")
@@ -1119,10 +1431,23 @@ def _write_text(path: str, content: str) -> None:
 # Note: `prepare` command has been removed; configuration now prepares TOML
 
 
-def cmd_run(args: argparse.Namespace) -> int:
+def run(
+    config: str | None = None,
+    batch_size: int | None = None,
+    group_size: int | None = None,
+    model: str | None = None,
+    timeout: int = 600,
+    dry_run: bool = False,
+) -> int:
+    # Change to demo directory if stored
+    demo_dir = demo_core.load_demo_dir()
+    if demo_dir and os.path.isdir(demo_dir):
+        os.chdir(demo_dir)
+        print(f"Using demo directory: {demo_dir}")
+
     env = demo_core.load_env()
     cwd_env_path = os.path.join(os.getcwd(), ".env")
-    local_env = demo_core.load_dotenv_file(cwd_env_path)
+    demo_core.load_dotenv_file(cwd_env_path)
 
     synth_key = (env.synth_api_key or "").strip()
     if not synth_key:
@@ -1154,7 +1479,7 @@ def cmd_run(args: argparse.Namespace) -> int:
     import tomllib
 
     try:
-        cfg_path = _select_or_create_config(getattr(args, "config", None), env)
+        cfg_path = _select_or_create_config(config, env)
     except FileNotFoundError as exc:
         print(exc)
         return 1
@@ -1162,7 +1487,11 @@ def cmd_run(args: argparse.Namespace) -> int:
     # Detect monorepo launcher and delegate if available (aligns with run_clustered.sh which works)
     launcher = "/Users/joshpurtell/Documents/GitHub/monorepo/tests/applications/math/rl/start_math_clustered.py"
     if os.path.isfile(launcher):
-        backend_base = env.dev_backend_url[:-4] if env.dev_backend_url.endswith("/api") else env.dev_backend_url
+        backend_base = (
+            env.dev_backend_url[:-4]
+            if env.dev_backend_url.endswith("/api")
+            else env.dev_backend_url
+        )
         run_env = os.environ.copy()
         run_env["BACKEND_URL"] = backend_base
         run_env["SYNTH_API_KEY"] = env.synth_api_key
@@ -1170,14 +1499,14 @@ def cmd_run(args: argparse.Namespace) -> int:
         run_env["ENVIRONMENT_API_KEY"] = env.env_api_key
         run_env["RL_CONFIG_PATH"] = cfg_path
         # Optional: TRAINER_START_URL passthrough if already set in environment
-        run_env["TRAINER_START_URL"] = run_env.get("TRAINER_START_URL", "")
+        run_env["TRAINER_START_URL"] = run_env.get("TRAINER_START_URL", "")  # type: ignore[misc]
         # Forward convenience knobs
-        if args.batch_size is not None:
-            run_env["RL_BATCH_SIZE"] = str(int(args.batch_size))
-        if args.group_size is not None:
-            run_env["RL_GROUP_SIZE"] = str(int(args.group_size))
-        if args.model:
-            run_env["RL_MODEL"] = args.model
+        if batch_size is not None:
+            run_env["RL_BATCH_SIZE"] = str(int(batch_size))
+        if group_size is not None:
+            run_env["RL_GROUP_SIZE"] = str(int(group_size))
+        if model:
+            run_env["RL_MODEL"] = model
         cmd = ["uv", "run", "python", launcher]
         print(f"Launching monorepo clustered runner: {' '.join(cmd)}")
         code = _popen_stream(cmd, env=run_env)
@@ -1192,33 +1521,33 @@ def cmd_run(args: argparse.Namespace) -> int:
             ek = (env.env_api_key or "").strip()
             print("Hint: If backend responded 401, verify SYNTH_API_KEY for:", base_url)
             if sk:
-                print(f"  SYNTH_API_KEY len={len(sk)} last5={sk[-5:]}")
+                print(f"  {_key_preview(sk, 'SYNTH_API_KEY')}")
             if ek:
-                print(f"  ENVIRONMENT_API_KEY len={len(ek)} last5={ek[-5:]}")
-            print("Also ensure your Modal secret contains ENVIRONMENT_API_KEY and matches the task app.")
+                print(f"  {_key_preview(ek, 'ENVIRONMENT_API_KEY')}")
+            print(
+                "Ensure the ENVIRONMENT_API_KEY you deployed with matches the task app and remains exported."
+            )
         return code
 
     # Fallback: legacy jobs API flow
     with open(cfg_path, "rb") as fh:
         inline_cfg = tomllib.load(fh)
-    with open(cfg_path, "r") as fh2:
+    with open(cfg_path) as fh2:
         toml_text = fh2.read()
-    if args.batch_size is not None:
-        inline_cfg.setdefault("training", {})["batch_size"] = int(args.batch_size)
-    if args.group_size is not None:
-        inline_cfg.setdefault("training", {})["group_size"] = int(args.group_size)
-    model_name = args.model or (inline_cfg.get("model", {}) or {}).get("name", "Qwen/Qwen3-0.6B")
+    if batch_size is not None:
+        inline_cfg.setdefault("training", {})["batch_size"] = int(batch_size)
+    if group_size is not None:
+        inline_cfg.setdefault("training", {})["group_size"] = int(group_size)
+    model_name = model or (inline_cfg.get("model", {}) or {}).get("name", "Qwen/Qwen3-0.6B")  # type: ignore[misc]
     api = env.dev_backend_url.rstrip("/") + ("" if env.dev_backend_url.endswith("/api") else "/api")
     # Print backend and key preview before request for clearer diagnostics
     try:
         sk = (env.synth_api_key or "").strip()
-        sk_len = len(sk)
-        sk_tail = sk[-5:] if sk_len >= 5 else sk
         print(f"[run] Backend API: {api}")
-        print(f"[run] Using SYNTH_API_KEY len={sk_len} last5={sk_tail}")
+        print(f"[run] {_key_preview(sk, 'SYNTH_API_KEY')}")
     except Exception:
         pass
-    data_fragment: Dict[str, Any] = {
+    data_fragment: dict[str, Any] = {
         "model": model_name,
         "endpoint_base_url": env.task_app_base_url,
         "config": inline_cfg,
@@ -1229,30 +1558,35 @@ def cmd_run(args: argparse.Namespace) -> int:
     if env.env_api_key:
         data_fragment["environment_api_key"] = env.env_api_key
     for k in ("training", "evaluation", "rollout", "topology", "vllm"):
-        if isinstance(inline_cfg.get(k), dict):
+        if isinstance(inline_cfg.get(k), dict):  # type: ignore[misc]
             data_fragment[k] = inline_cfg[k]
     compute = {}
-    if isinstance(inline_cfg.get("compute"), dict):
-        if inline_cfg["compute"].get("gpu_type"):
+    if isinstance(inline_cfg.get("compute"), dict):  # type: ignore[misc]
+        if inline_cfg["compute"].get("gpu_type"):  # type: ignore[misc]
             compute["gpu_type"] = str(inline_cfg["compute"]["gpu_type"]).upper()
-        if inline_cfg["compute"].get("gpu_count"):
-            compute["gpu_count"] = int(inline_cfg["compute"]["gpu_count"]) 
+        if inline_cfg["compute"].get("gpu_count"):  # type: ignore[misc]
+            compute["gpu_count"] = int(inline_cfg["compute"]["gpu_count"])
     if not compute:
-        topo = inline_cfg.get("topology") or {}
-        gshape = str(topo.get("gpu_type") or "")
+        topo = inline_cfg.get("topology") or {}  # type: ignore[misc]
+        gshape = str(topo.get("gpu_type") or "")  # type: ignore[misc]
         if ":" in gshape:
             t, c = gshape.split(":", 1)
             compute = {"gpu_type": t.upper(), "gpu_count": int(c)}
-    body: Dict[str, Any] = {
+    body: dict[str, Any] = {
         "job_type": "rl",
         "data": data_fragment,
     }
     if compute:
         body["compute"] = compute
-    code, js = _http("POST", api + "/rl/jobs", headers={
-        "Content-Type": "application/json",
-        "Authorization": f"Bearer {env.synth_api_key}",
-    }, body=body)
+    code, js = _http(
+        "POST",
+        api + "/rl/jobs",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {env.synth_api_key}",
+        },
+        body=body,
+    )
     if code not in (200, 201) or not isinstance(js, dict):
         print("Job create failed:", code)
         print(f"Backend: {api}")
@@ -1264,19 +1598,81 @@ def cmd_run(args: argparse.Namespace) -> int:
         except Exception:
             print(str(js))
         print("Request body was:\n" + json.dumps(body, indent=2))
+        try:
+            auth_preview = _key_preview(env.synth_api_key or "", "SYNTH_API_KEY (auth)")
+            print(f"[run] {auth_preview}")
+        except Exception:
+            pass
+        try:
+            data_block = body.get("data") if isinstance(body, dict) else None  # type: ignore[misc]
+            env_key_body = ""
+            if isinstance(data_block, dict):
+                env_key_body = str(data_block.get("environment_api_key") or "")  # type: ignore[misc]
+            if env_key_body:
+                print(f"[run] {_key_preview(env_key_body, 'environment_api_key (body)')}")
+        except Exception:
+            pass
+        try:
+            current_env_key = env.env_api_key or ""
+            if current_env_key:
+                print(f"[run] {_key_preview(current_env_key, 'ENVIRONMENT_API_KEY (current)')}")
+        except Exception:
+            pass
+        if isinstance(js, dict):
+            detail = js.get("detail")  # type: ignore[misc]
+            if isinstance(detail, dict):
+                try:
+                    sent_key = detail.get("sent_key")  # type: ignore[misc]
+                    if isinstance(sent_key, str):
+                        print(
+                            f"[run] Backend detail.sent_key {_key_preview(sent_key, 'detail.sent_key')}"
+                        )
+                except Exception:
+                    pass
+                try:
+                    sent_keys = detail.get("sent_keys")  # type: ignore[misc]
+                    if isinstance(sent_keys, list | tuple):
+                        previews = []
+                        for idx, val in enumerate(sent_keys):
+                            if isinstance(val, str):
+                                previews.append(_key_preview(val, f"detail.sent_keys[{idx}]"))
+                        if previews:
+                            joined = "; ".join(previews)
+                            print(f"[run] Backend detail.sent_keys previews: {joined}")
+                except Exception:
+                    pass
+                try:
+                    key_prefix = detail.get("sent_key_prefix")  # type: ignore[misc]
+                    if isinstance(key_prefix, str):
+                        print(f"[run] Backend detail.sent_key_prefix={key_prefix}")
+                except Exception:
+                    pass
+                try:
+                    health_url = detail.get("health_url")
+                    if isinstance(health_url, str):
+                        print(f"[run] Backend detail.health_url={health_url}")
+                except Exception:
+                    pass
         # Extra hints for auth failures
         try:
             sk = (env.synth_api_key or "").strip()
-            if int(code) == 401 or (isinstance(js, dict) and any(isinstance(v, str) and "Invalid API key" in v for v in js.values())):
+            if int(code) == 401 or (
+                isinstance(js, dict)
+                and any(isinstance(v, str) and "Invalid API key" in v for v in js.values())
+            ):
                 base_url = env.dev_backend_url
-                print("Hint: HTTP 401 Unauthorized from backend. Verify SYNTH_API_KEY for:", base_url)
+                print(
+                    "Hint: HTTP 401 Unauthorized from backend. Verify SYNTH_API_KEY for:", base_url
+                )
                 if sk:
-                    print(f"  SYNTH_API_KEY len={len(sk)} last5={sk[-5:]}")
-                print("Also ensure your Modal secret contains a valid ENVIRONMENT_API_KEY.")
+                    print(f"  {_key_preview(sk, 'SYNTH_API_KEY')}")
+                print(
+                    "Ensure the ENVIRONMENT_API_KEY and OPENAI_API_KEY used for deployment remain valid."
+                )
         except Exception:
             pass
         return 2
-    job_id = js.get("job_id") or js.get("id") or ""
+    job_id = js.get("job_id") or js.get("id") or ""  # type: ignore[misc]
     if not job_id:
         print("Job id missing in response:", js)
         print("Request body was:\n" + json.dumps(body, indent=2))
@@ -1296,7 +1692,7 @@ def cmd_run(args: argparse.Namespace) -> int:
     start_t = time.time()
     while True:
         sc, sj = _http("GET", api + f"/learning/jobs/{job_id}")
-        status = (sj.get("status") if isinstance(sj, dict) else "") if sc == 200 else ""
+        status = (sj.get("status") if isinstance(sj, dict) else "") if sc == 200 else ""  # type: ignore[misc]
         if status and status != last_status:
             last_status = status
             print("status →", status)
@@ -1308,14 +1704,14 @@ def cmd_run(args: argparse.Namespace) -> int:
             api + f"/orchestration/jobs/{job_id}/events?since_seq={since}&limit=200",
         )
         if ec == 200 and isinstance(ej, dict):
-            events = ej.get("events") or ej.get("data") or []
+            events = ej.get("events") or ej.get("data") or []  # type: ignore[misc]
             for e in events:
                 seq = int(e.get("seq") or 0)
                 if seq <= since:
                     continue
                 since = seq
-                typ = str(e.get("type") or e.get("event_type") or "").lower()
-                msg = e.get("message") or e.get("msg") or ""
+                typ = str(e.get("type") or e.get("event_type") or "").lower()  # type: ignore[misc]
+                msg = e.get("message") or e.get("msg") or ""  # type: ignore[misc]
                 if typ in (
                     "rl.eval.started",
                     "rl.eval.summary",
@@ -1324,70 +1720,16 @@ def cmd_run(args: argparse.Namespace) -> int:
                     "rl.performance.metrics",
                 ):
                     print(f"[{seq}] {typ}: {msg}")
-        mc, mj = _http(
-            "GET", api + f"/learning/jobs/{job_id}/metrics?after_step=-1&limit=50"
-        )
+        mc, mj = _http("GET", api + f"/learning/jobs/{job_id}/metrics?after_step=-1&limit=50")
         if mc == 200 and isinstance(mj, dict):
-            pts = mj.get("points") or []
+            pts = mj.get("points") or []  # type: ignore[misc]
             for p in pts:
-                name = p.get("name")
+                name = p.get("name")  # type: ignore[misc]
                 if name == "eval.reward_mean":
-                    print(f"metric eval.reward_mean step={p.get('step')} value={p.get('value')}")
+                    print(f"metric eval.reward_mean step={p.get('step')} value={p.get('value')}")  # type: ignore[misc]
                     break
-        if time.time() - start_t > (args.timeout or 600):
+        if time.time() - start_t > (timeout or 600):
             print("Timeout waiting for terminal state.")
             break
         time.sleep(2)
     return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    p = argparse.ArgumentParser(prog="synth-ai")
-    sub = p.add_subparsers(dest="cmd")
-
-    def _add_parser(names: list[str], *, configure: Callable[[argparse.ArgumentParser], None]) -> None:
-        for name in names:
-            parser = sub.add_parser(name)
-            configure(parser)
-
-    _add_parser(["rl_demo.setup", "demo.setup"], configure=lambda parser: parser.set_defaults(func=cmd_setup))
-
-    def _init_opts(parser):
-        parser.add_argument("--force", action="store_true", help="Overwrite existing files in CWD")
-        parser.set_defaults(func=cmd_init)
-
-    _add_parser(["rl_demo.init", "demo.init"], configure=_init_opts)
-
-    # (prepare command removed)
-
-    def _deploy_opts(parser):
-        parser.add_argument("--local", action="store_true", help="Run local FastAPI instead of Modal deploy")
-        parser.add_argument("--app", type=str, default=None, help="Path to Modal app.py for uv run modal deploy")
-        parser.add_argument("--name", type=str, default="synth-math-demo", help="Modal app name")
-        parser.add_argument("--script", type=str, default=None, help="Path to deploy_task_app.sh (optional legacy)")
-        parser.set_defaults(func=cmd_deploy)
-
-    _add_parser(["rl_demo.deploy", "demo.deploy"], configure=_deploy_opts)
-
-    _add_parser(["rl_demo.configure", "demo.configure"], configure=lambda parser: parser.set_defaults(func=cmd_run))
-
-    def _run_opts(parser):
-        parser.add_argument("--config", type=str, default=None, help="Path to TOML config (skip prompt)")
-        parser.add_argument("--batch-size", type=int, default=None)
-        parser.add_argument("--group-size", type=int, default=None)
-        parser.add_argument("--model", type=str, default=None)
-        parser.add_argument("--timeout", type=int, default=600)
-        parser.add_argument("--dry-run", action="store_true", help="Print request body and exit")
-        parser.set_defaults(func=cmd_run)
-
-    _add_parser(["run", "rl_demo.run", "demo.run"], configure=_run_opts)
-
-    args = p.parse_args(argv)
-    if not hasattr(args, "func"):
-        p.print_help()
-        return 1
-    return int(args.func(args) or 0)
-
-
-if __name__ == "__main__":
-    sys.exit(main())