@qubiqlabs/mobiflow 0.9.0 → 1.0.0

package/src/mobiflow/init/__init__.py

@@ -0,0 +1,794 @@
+"""Terminal-only interactive setup wizard."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+import questionary
+from rich.console import Console
+from rich.panel import Panel
+from rich.rule import Rule
+
+from mobiflow.cases import EXAMPLE_CASE
+from mobiflow.config import (
+    CONFIG_FILENAME,
+    DeviceConfig,
+    LlmConfig,
+    MobiflowConfig,
+    ProjectConfig,
+    ProjectMode,
+    RunConfig,
+    StackConfig,
+    save_config,
+)
+
+console = Console()
+
+_BANNER = r"""
+ __  __       _     _ _____ _
+|  \/  | ___ | |__ (_)  ___| | _____      __
+| |\/| |/ _ \| '_ \| | |_  | |/ _ \ \ /\ / /
+| |  | | (_) | |_) | |  _| | | (_) \ V  V /
+|_|  |_|\___/|_.__/|_|_|   |_|\___/ \_/\_/
+"""
+
+_CASES_README = """# mobiflow test cases
+
+Put **one plain-text file per scenario** in this folder (`.txt`).
+
+## Intent style
+
+```text
+appId: org.wikipedia
+platform: android
+task: Open Wikipedia, dismiss onboarding, confirm Search is visible
+```
+
+## Guided steps
+
+```text
+@smoke
+appId: com.android.settings
+platform: android
+
+1. Launch Settings
+2. Confirm Wi-Fi or Network is visible
+```
+
+## Commands
+
+```bash
+mobiflow run cases/example.txt
+mobiflow run cases/example.txt --gen-only
+mobiflow devices
+mobiflow status
+```
+"""
+
+
+def _project_guide(*, repo: Path, llm: LlmConfig, stack: StackConfig, device: DeviceConfig) -> str:
+    azure_extra = ""
+    if (llm.provider or "").lower().startswith("azure") or (
+        llm.discovery and "azure" in (llm.discovery or "")
+    ):
+        azure_extra = (
+            f"\nexport {llm.azure_endpoint_env}=https://YOUR.openai.azure.com\n"
+        )
+    return f"""# MobiFlow — project guide
+
+Generated by `mobiflow init`.
+
+## What was added
+
+| Path | Purpose |
+|------|---------|
+| `mobiflow.config.yaml` | Picks discovery/codegen models + device/run |
+| `llm.json` | Catalog of Azure / OpenAI / Anthropic / Google models |
+| `cases/` | Plain-text scenarios (one `.txt` each) |
+| `flows/` | Generated Maestro YAML |
+| `.mobiflow/` | Run artifacts (created on first run) |
+| `MOBIFLOW.md` | This guide |
+
+## 1. Models (`llm.json`) + selection
+
+```yaml
+llm:
+  catalog: llm.json
+  discovery: azure-gpt4o      # adaptive explore / plan
+  codegen: anthropic-sonnet   # Maestro YAML authoring
+```
+
+```bash
+export {llm.api_key_env}=your-key{azure_extra}
+mobiflow llm list
+```
+
+Discovery: `{llm.discovery or 'default'}` · Codegen: `{llm.codegen or llm.discovery or 'default'}`  
+Stack: **{stack.tool}** / **{stack.language}** / `{stack.flow_dir}` · Platform: **{device.platform}** · appId: `{device.app_id or '(per case)'}`
+
+JavaScript: Maestro GraalJS via `${{…}}`, `evalScript`, and `runScript: scripts/*.js` when `stack.language` is `yaml+js`.
+
+## 2. Add a case
+
+```bash
+cp cases/example.txt cases/my-flow.txt
+# edit appId / platform / task
+mobiflow run cases/my-flow.txt
+```
+
+## 3. Commands
+
+```bash
+cd {repo}
+
+mobiflow status              # Maestro CLI + devices
+mobiflow devices             # adb + booted simulators
+mobiflow setup               # install missing Maestro / JDK / pip packages
+mobiflow run cases/example.txt
+mobiflow run cases/example.txt --gen-only   # YAML only
+mobiflow run cases/example.txt --no-heal
+mobiflow gen "Open Settings and assert visible" --platform android
+mobiflow config show
+mobiflow llm list
+```
+
+## 4. Prerequisites
+
+`mobiflow init` (step 4) and `mobiflow setup` can auto-install Maestro, JDK (via Homebrew), and missing pip packages. You still need:
+
+- Python 3.11+
+- Android emulator and/or iOS Simulator for live runs
+- LLM API key for the profile selected in `llm.json`
+
+Secrets never go in `mobiflow.config.yaml` — only env var **names**.
+"""
+
+
+def _fail(msg: str) -> None:
+    console.print(f"[red]{msg}[/red]")
+    raise SystemExit(1)
+
+
+def _ok(msg: str) -> None:
+    console.print(f"  [green]✓[/green] {msg}")
+
+
+def _warn(msg: str) -> None:
+    console.print(f"  [yellow]![/yellow] {msg}")
+
+
+_WIZARD_STEPS = 5
+
+
+def _step(n: int, title: str) -> None:
+    console.print()
+    console.print(Rule(f"[bold cyan]Step {n}/{_WIZARD_STEPS}[/bold cyan] — {title}"))
+
+
+def _require(val, *, what: str):
+    if val is None:
+        _fail(f"Cancelled while asking for {what}.")
+    return val
+
+
+def _ask_line(prompt: str, *, what: str, default: str = "", required: bool = True) -> str:
+    kwargs = {}
+    if default:
+        kwargs["default"] = default
+    ans = questionary.text(prompt, **kwargs).ask()
+    if ans is None:
+        _fail(f"Cancelled while asking for {what}.")
+    ans = str(ans).strip()
+    if required and not ans:
+        _fail(f"{what} cannot be empty.")
+    return ans
+
+
+def run_init(
+    *,
+    mode: Optional[str] = None,
+    path: Optional[str] = None,
+    yes: bool = False,
+    install_deps: Optional[bool] = None,
+) -> Path:
+    if yes:
+        # Default: auto-install missing packages in non-interactive mode
+        do_install = True if install_deps is None else install_deps
+        return _init_noninteractive(mode=mode, path=path, install_deps=do_install)
+
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        _fail(
+            "Interactive `mobiflow init` needs a terminal.\n"
+            "  Use: mobiflow init --mode local --path . --yes"
+        )
+
+    try:
+        return _run_init_interactive(
+            mode=mode, path=path, install_deps=install_deps
+        )
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted.[/yellow]")
+        raise SystemExit(130) from None
+
+
+def _init_noninteractive(
+    *, mode: Optional[str], path: Optional[str], install_deps: bool = True
+) -> Path:
+    from mobiflow.llm_catalog import default_catalog_seed, save_catalog
+
+    mode_choice = (mode or "local").lower()
+    if mode_choice == "clone":
+        mode_choice = "local"
+    repo = Path(path or ".").expanduser().resolve()
+    repo.mkdir(parents=True, exist_ok=True)
+
+    catalog = default_catalog_seed()
+    save_catalog(catalog, repo)
+    names = catalog.names()
+    default = names[0]
+    for n in names:
+        if catalog.models[n].provider.lower().startswith("azure"):
+            default = n
+            break
+
+    llm = LlmConfig(
+        catalog="llm.json",
+        discovery=default,
+        codegen=default,
+        provider=catalog.models[default].provider,
+        model=catalog.models[default].model,
+        api_key_env=catalog.models[default].api_key_env,
+        endpoint=catalog.models[default].endpoint,
+    )
+    stack = StackConfig(language="yaml+js", scripts_dir="flows/scripts")
+    device = DeviceConfig(platform="android", app_id="")
+    config = MobiflowConfig(
+        project=ProjectConfig(mode=ProjectMode(mode_choice if mode_choice != "clone" else "local"), path=str(repo)),
+        llm=llm,
+        stack=stack,
+        device=device,
+        run=RunConfig(),
+    )
+    out = save_config(config, repo)
+    _ensure_project_docs(repo, config)
+    console.print(f"[green]Wrote[/green] {out}")
+    console.print(f"[green]Wrote[/green] {repo / 'llm.json'}")
+
+    if install_deps:
+        _run_deps_setup(
+            want_anthropic=catalog.models[default].provider.lower()
+            in ("anthropic", "claude"),
+            install_adb=False,
+            auto=True,
+        )
+    else:
+        console.print("[dim]Skipped dependency install (--no-install-deps)[/dim]")
+
+    console.print(f"[dim]Export your API key, then: mobiflow run cases/example.txt[/dim]")
+    return out
+
+
+def _run_init_interactive(
+    *,
+    mode: Optional[str],
+    path: Optional[str],
+    install_deps: Optional[bool],
+) -> Path:
+    console.print(_BANNER, style="bold cyan")
+    console.print(
+        Panel(
+            "[bold]Setup wizard[/bold]\n"
+            "[dim]Guided[/dim]  "
+            "[cyan]1[/cyan] project  →  [cyan]2[/cyan] LLM  →  "
+            "[cyan]3[/cyan] device  →  [cyan]4[/cyan] deps  →  [cyan]5[/cyan] finish",
+            border_style="dim",
+            padding=(0, 2),
+        )
+    )
+
+    # Step 1 — project
+    _step(1, "Project path")
+    mode_choice = mode
+    if mode_choice is None:
+        mode_choice = _require(
+            questionary.select(
+                "How do you want to start?",
+                choices=[
+                    questionary.Choice("Use current / local path", value="local"),
+                    questionary.Choice("Connect an existing folder", value="existing"),
+                    questionary.Choice("Start a fresh scaffold", value="new"),
+                ],
+                default="local",
+            ).ask(),
+            what="project mode",
+        )
+    mode_choice = str(mode_choice).lower()
+    if path:
+        project_path = path
+    else:
+        project_path = _ask_line(
+            "Project path",
+            what="project path",
+            default=str(Path.cwd()),
+            required=True,
+        )
+    repo = Path(str(project_path)).expanduser().resolve()
+    repo.mkdir(parents=True, exist_ok=True)
+    _ok(f"Using project at {repo}")
+
+    existing = repo / CONFIG_FILENAME
+    if existing.exists():
+        overwrite = questionary.confirm(
+            f"{CONFIG_FILENAME} already exists. Overwrite?",
+            default=False,
+        ).ask()
+        if overwrite is None:
+            _fail("Cancelled while confirming overwrite.")
+        if not overwrite:
+            console.print("[yellow]Aborted — existing config left unchanged.[/yellow]")
+            return existing
+
+    # Step 2 — LLM
+    _step(2, "LLM catalog & model selection")
+    llm = _ask_llm(repo)
+
+    # Step 3 — device / stack
+    _step(3, "Device defaults & Maestro stack")
+    provider = _require(
+        questionary.select(
+            "Device lab:",
+            choices=[
+                questionary.Choice("Local (adb / Android AVD / iOS Simulator)", value="local"),
+                questionary.Choice("Maestro Cloud (official `maestro cloud`)", value="maestro"),
+                questionary.Choice("BrowserStack App Automate (Maestro)", value="browserstack"),
+                questionary.Choice("TestMu AI / HyperExecute (Maestro)", value="testmu"),
+            ],
+            default="local",
+        ).ask(),
+        what="provider",
+    )
+    platform = _require(
+        questionary.select(
+            "Default platform:",
+            choices=["android", "ios"],
+            default="android",
+        ).ask(),
+        what="platform",
+    )
+    app_id = _ask_line(
+        "Default appId (Enter to leave empty — set per case)",
+        what="appId",
+        default="",
+        required=False,
+    )
+    device_kwargs: dict = {"provider": str(provider), "platform": platform, "app_id": app_id}
+    if provider != "local":
+        if provider == "maestro":
+            default_device = "pixel_7" if platform == "android" else "iPhone-16"
+            device_prompt = "Maestro Cloud device model (e.g. pixel_7, iPhone-16)"
+            app_prompt = (
+                "Path to .apk / .ipa to upload "
+                "(or leave empty if using an existing Maestro app binary id later)"
+            )
+        elif provider == "browserstack":
+            default_device = (
+                "Google Pixel 7-13.0" if platform == "android" else "iPhone 15-17.0"
+            )
+            device_prompt = "Cloud device name (comma-separated for multiple)"
+            app_prompt = (
+                "Path to .apk / .ipa to upload (or leave empty if using app_url later)"
+            )
+        else:
+            default_device = "Pixel 6-14" if platform == "android" else "iPhone 15"
+            device_prompt = "Cloud device name (comma-separated for multiple)"
+            app_prompt = (
+                "Path to .apk / .ipa to upload (or leave empty if using app_url later)"
+            )
+        cloud_device = _ask_line(
+            device_prompt,
+            what="device_id",
+            default=default_device,
+            required=True,
+        )
+        app_path = _ask_line(
+            app_prompt,
+            what="app_path",
+            default="",
+            required=False,
+        )
+        device_kwargs["device_id"] = cloud_device
+        device_kwargs["app_path"] = app_path
+        device_kwargs["auto_start"] = False
+        if provider == "maestro":
+            console.print(
+                "[dim]Credentials: export MAESTRO_CLOUD_API_KEY=… "
+                "(or MAESTRO_API_KEY) before `mobiflow run`.[/dim]"
+            )
+        if provider == "testmu":
+            real = questionary.confirm(
+                "Use real devices on TestMu? (No = virtual emulator/simulator)",
+                default=True,
+            ).ask()
+            device_kwargs["real_mobile"] = bool(real)
+    device = DeviceConfig(**device_kwargs)
+    language = _require(
+        questionary.select(
+            "Maestro authoring language:",
+            choices=[
+                questionary.Choice(
+                    "YAML + JavaScript (evalScript / runScript) — recommended",
+                    value="yaml+js",
+                ),
+                questionary.Choice("YAML only", value="yaml"),
+            ],
+            default="yaml+js",
+        ).ask(),
+        what="language",
+    )
+    stack = StackConfig(
+        tool="maestro",
+        language=str(language),
+        runner="maestro",
+        scripts_dir="flows/scripts",
+    )
+    _ok(
+        f"Stack: maestro / {language} · provider={provider} · "
+        f"platform={platform} · appId={app_id or '(per case)'}"
+    )
+
+    # Step 4 — missing packages / tools
+    _step(4, "Install missing packages & tools")
+    want_anthropic = (llm.provider or "").lower() in ("anthropic", "claude")
+    if not want_anthropic:
+        # Also check selected catalog profile ids
+        for name in (llm.discovery, llm.codegen):
+            if name and "anthropic" in name.lower():
+                want_anthropic = True
+                break
+
+    from mobiflow.deps import probe_dependencies
+
+    probed = probe_dependencies(want_anthropic=want_anthropic)
+    missing = [i for i in probed if not i.ok]
+    installable = [i for i in missing if i.installable]
+    for item in probed:
+        mark = "[green]OK[/green]" if item.ok else "[yellow]MISSING[/yellow]"
+        console.print(f"  {mark}  {item.label}")
+        if not item.ok and item.detail:
+            console.print(f"       [dim]{item.detail}[/dim]")
+
+    do_install = install_deps
+    install_adb = False
+    if do_install is None:
+        if installable:
+            answer = questionary.confirm(
+                "Automatically install missing packages/tools now?",
+                default=True,
+            ).ask()
+            if answer is None:
+                _fail("Cancelled while asking about dependency install.")
+            do_install = bool(answer)
+        else:
+            do_install = False
+            if not missing:
+                _ok("All checked dependencies are available")
+            else:
+                _warn("Some optional tools are missing (not auto-installable here)")
+
+    if do_install and installable:
+        adb_missing = any(i.id == "adb" and not i.ok and i.installable for i in probed)
+        if adb_missing and platform_wants_android(platform):
+            adb_ans = questionary.confirm(
+                "Also install Android platform-tools (adb) via Homebrew?",
+                default=True,
+            ).ask()
+            install_adb = bool(adb_ans)
+        _run_deps_setup(
+            want_anthropic=want_anthropic,
+            install_adb=install_adb,
+            auto=True,
+        )
+    elif do_install and not installable:
+        _warn("Nothing installable automatically — see notes above")
+    else:
+        _warn("Skipped dependency install")
+
+    # Step 5 — write
+    _step(5, "Write config & finish")
+    try:
+        pm = ProjectMode.NEW if mode_choice == "new" else (
+            ProjectMode.EXISTING if mode_choice == "existing" else ProjectMode.LOCAL
+        )
+        config = MobiflowConfig(
+            project=ProjectConfig(mode=pm, path=str(repo)),
+            llm=llm,
+            stack=stack,
+            device=device,
+            run=RunConfig(heal=2, adaptive=True),
+        )
+        out = save_config(config, repo)
+        _ensure_project_docs(repo, config)
+    except Exception as e:  # noqa: BLE001
+        _fail(f"Failed to write config: {e}")
+
+    _ok(f"Wrote {out}")
+    _ok(f"LLM catalog  → {repo / 'llm.json'}")
+    _ok(f"Docs         → {repo / 'MOBIFLOW.md'}")
+    _ok(f"Example case → {repo / 'cases' / 'example.txt'}")
+    _print_usage(repo, llm)
+    return out
+
+
+def platform_wants_android(platform: str) -> bool:
+    return (platform or "").lower() == "android"
+
+
+def _run_deps_setup(
+    *,
+    want_anthropic: bool,
+    install_adb: bool,
+    auto: bool,
+) -> None:
+    from mobiflow.deps import install_missing, probe_dependencies
+
+    def _log(msg: str) -> None:
+        console.print(f"[dim]{msg}[/dim]")
+
+    if not auto:
+        return
+
+    report = install_missing(
+        want_anthropic=want_anthropic,
+        install_adb=install_adb,
+        log=_log,
+    )
+    for action in report.actions:
+        _ok(action)
+    for err in report.errors:
+        _warn(err)
+
+    # Final status
+    still = [i for i in report.items if not i.ok and i.required]
+    if still:
+        _warn("Still missing (manual install needed):")
+        for i in still:
+            console.print(f"       · {i.label}: {i.detail}")
+    else:
+        _ok("Required dependencies look good")
+    # Refresh optional display
+    optional_missing = [i for i in probe_dependencies(want_anthropic=want_anthropic) if not i.ok and not i.required]
+    for i in optional_missing:
+        console.print(f"  [dim]optional missing:[/dim] {i.label}")
+
+
+def _ask_llm(repo: Path) -> LlmConfig:
+    from mobiflow.llm_catalog import (
+        ModelEntry,
+        default_catalog_seed,
+        load_catalog,
+        save_catalog,
+    )
+
+    catalog_file = repo / "llm.json"
+    if catalog_file.exists():
+        catalog = load_catalog(repo)
+        console.print(f"  Found existing [cyan]llm.json[/cyan] ({len(catalog.models)} models)")
+    else:
+        catalog = default_catalog_seed()
+        save_catalog(catalog, repo)
+        _ok(f"Wrote starter catalog → {catalog_file}")
+        console.print(
+            "  [dim]Edit llm.json anytime to add Azure / OpenAI / Anthropic / Google models.[/dim]"
+        )
+
+    add_more = questionary.confirm(
+        "Add or update a model profile in llm.json now?",
+        default=not catalog_file.exists() or len(catalog.models) < 2,
+    ).ask()
+    if add_more is None:
+        _fail("Cancelled while asking about llm.json.")
+    while add_more:
+        entry_id, entry = _ask_model_entry()
+        catalog.models[entry_id] = entry
+        save_catalog(catalog, repo)
+        _ok(f"Saved profile [cyan]{entry_id}[/cyan] → {entry.display_name}")
+        add_more = bool(
+            questionary.confirm("Add another model profile?", default=False).ask()
+        )
+
+    names = catalog.names()
+    if not names:
+        _fail("llm.json has no models. Add at least one profile.")
+
+    choices = [
+        questionary.Choice(
+            title=f"{n} — {catalog.models[n].display_name} ({catalog.models[n].provider})",
+            value=n,
+        )
+        for n in names
+    ]
+    default = names[0]
+    for n in names:
+        if catalog.models[n].provider.lower().startswith("azure"):
+            default = n
+            break
+
+    discovery = _require(
+        questionary.select(
+            "Discovery model (adaptive explore / plan on device):",
+            choices=choices,
+            default=default,
+        ).ask(),
+        what="discovery model",
+    )
+    codegen = _require(
+        questionary.select(
+            "Codegen model (Maestro YAML authoring):",
+            choices=choices,
+            default=discovery,
+        ).ask(),
+        what="codegen model",
+    )
+
+    for role, name in (("discovery", discovery), ("codegen", codegen)):
+        entry = catalog.models[name]
+        if os.environ.get(entry.api_key_env):
+            _ok(f"{role}: {entry.api_key_env} is set")
+        else:
+            _warn(f"{role}: export {entry.api_key_env}=... before `mobiflow run`")
+
+    return LlmConfig(
+        catalog="llm.json",
+        discovery=discovery,
+        codegen=codegen,
+        provider=catalog.models[discovery].provider,
+        model=catalog.models[discovery].model,
+        api_key_env=catalog.models[discovery].api_key_env,
+        endpoint=catalog.models[discovery].endpoint,
+    )
+
+
+def _ask_model_entry() -> tuple[str, "ModelEntry"]:
+    from mobiflow.llm_catalog import ModelEntry
+
+    provider = _require(
+        questionary.select(
+            "Provider:",
+            choices=["azure", "openai", "anthropic", "google"],
+            default="azure",
+        ).ask(),
+        what="provider",
+    )
+    entry_id = _require(
+        questionary.text(
+            "Profile id (used in mobiflow.config.yaml):",
+            default=f"{provider}-main",
+        ).ask(),
+        what="profile id",
+    )
+    entry_id = str(entry_id).strip().replace(" ", "-")
+    if not entry_id:
+        _fail("Profile id cannot be empty.")
+
+    defaults = {
+        "azure": ("gpt-4o", "AZURE_OPENAI_API_KEY"),
+        "openai": ("gpt-4o", "OPENAI_API_KEY"),
+        "anthropic": ("claude-sonnet-4-6", "ANTHROPIC_API_KEY"),
+        "google": ("gemini-2.0-flash", "GOOGLE_API_KEY"),
+    }
+    model_default, key_default = defaults.get(provider, ("gpt-4o", "MOBIFLOW_LLM_API_KEY"))
+
+    model = _require(
+        questionary.text(
+            "Model / base model id (e.g. gpt-4o, gpt-5.4):",
+            default=model_default,
+        ).ask(),
+        what="model name",
+    )
+    deployment = None
+    endpoint = None
+    if provider == "azure":
+        deployment = _require(
+            questionary.text(
+                "Azure deployment name:",
+                default=str(model).strip() or model_default,
+            ).ask(),
+            what="deployment",
+        )
+        endpoint = _ask_line(
+            "Azure endpoint URL (or leave empty and use AZURE_OPENAI_ENDPOINT):",
+            what="endpoint",
+            default="",
+            required=False,
+        ) or None
+
+    api_key_env = _require(
+        questionary.text("API key env var name:", default=key_default).ask(),
+        what="api_key_env",
+    )
+    label = _ask_line(
+        "Label (optional):",
+        what="label",
+        default=f"{provider}/{model}",
+        required=False,
+    )
+
+    return entry_id, ModelEntry(
+        provider=provider,
+        model=str(model).strip(),
+        deployment=str(deployment).strip() if deployment else None,
+        api_key_env=str(api_key_env).strip(),
+        endpoint=endpoint,
+        label=label or None,
+    )
+
+
+def _ensure_project_docs(repo: Path, config: MobiflowConfig) -> None:
+    from mobiflow.maestro import DEFAULT_HELPERS_JS
+
+    cases = repo / config.stack.cases_dir
+    flows = repo / config.stack.flow_dir
+    scripts = repo / "flows" / "scripts"
+    cases.mkdir(parents=True, exist_ok=True)
+    flows.mkdir(parents=True, exist_ok=True)
+    scripts.mkdir(parents=True, exist_ok=True)
+
+    example = cases / "example.txt"
+    if not example.exists():
+        # Prefer Wikipedia on android by default
+        text = EXAMPLE_CASE
+        if config.device.app_id:
+            text = text.replace("org.wikipedia", config.device.app_id, 1)
+        if config.device.platform:
+            text = text.replace("platform: android", f"platform: {config.device.platform}", 1)
+        example.write_text(text, encoding="utf-8")
+
+    helpers = scripts / "helpers.js"
+    if config.stack.js_enabled() and not helpers.exists():
+        helpers.write_text(DEFAULT_HELPERS_JS, encoding="utf-8")
+
+    (cases / "README.md").write_text(_CASES_README, encoding="utf-8")
+    (repo / "MOBIFLOW.md").write_text(
+        _project_guide(
+            repo=repo,
+            llm=config.llm,
+            stack=config.stack,
+            device=config.device,
+        ),
+        encoding="utf-8",
+    )
+    (flows / ".gitkeep").write_text("", encoding="utf-8")
+
+    # Example flow that demonstrates runScript when JS is enabled
+    if config.stack.js_enabled():
+        demo = flows / "example_with_js.yaml"
+        if not demo.exists():
+            demo.write_text(
+                """\
+appId: com.android.settings
+name: Settings smoke with JS helper
+---
+- runScript: scripts/helpers.js
+- evalScript: ${setOutput('runId', 'demo-' + Date.now())}
+- launchApp
+- assertVisible: "Settings|Network|Apps|Wi-Fi"
+- stopApp
+""",
+                encoding="utf-8",
+            )
+
+
+def _print_usage(repo: Path, llm: LlmConfig) -> None:
+    console.print()
+    console.print(Panel.fit(
+        f"[bold]Next steps[/bold]\n\n"
+        f"  export {llm.api_key_env}=...\n"
+        f"  cd {repo}\n"
+        f"  mobiflow status\n"
+        f"  mobiflow run cases/example.txt\n\n"
+        f"[dim]Guide: MOBIFLOW.md · Models: llm.json · Config: mobiflow.config.yaml[/dim]",
+        border_style="cyan",
+    ))