feat(lpb): first-boot lemonade URL prompt + host passthrough

- lpb.py: first-boot health probe of the lemonade server in --ssh/--web
  modes (TTY): unreachable -> prompt for the real host, then API key with
  default; resolved URL/key passed to the container as LPB_LEMONADE_* so
  the non-interactive first-boot setup (lpb-config setup) gets the right
  server (lemonade on a different host than 127.0.0.1)
- static passthrough always: shell env LPB_/bare LEMONADE_BASE_URL &
  LEMONADE_API_KEY, then lpb.conf.env (LPB_ wins)
- foreground Pi/shell modes: no host prompt (in-container interactive
  wizard handles it, pre-filled from the same env)
- testharness: deterministic non-TTY stdin default (no input() hangs)
- tests: test_lpb_lemonade.py (9 tests), registered in test_lpb.py
- docs: README, lpb-cli (new section), env-vars, lpb-config

Author: localpibox

README.md

@@ -26,15 +26,17 @@ lpb                              # resumes your last project (or ~)
 ```
 
 On the **first run** the container pulls the image, clones the config preset,
-generates `settings.json`, and installs the extensions. Before Pi starts, the
-**first-run setup wizard** walks you through connecting your Lemonade server:
-
-1. server URL (pre-filled from `LEMONADE_BASE_URL`, health-checked)
-2. API key (a placeholder like `lemonade` is fine for a local server)
-3. default model (picked from the server's model list)
-4. lpb-memory configuration
-
-After that Pi starts fully configured. Re-run it any time inside the
+generates `settings.json`, and installs the extensions. First-run setup then
+connects your Lemonade server:
+
+- **`--ssh` / `--web`** (background): `lpb` prompts in its own terminal for
+  the server URL (health-checked — type the real host if
+  `127.0.0.1:13305` is unreachable) and API key, then the container finishes
+  setup non-interactively: default model (from the server's model list) and
+  lpb-memory configuration.
+- **Foreground Pi / shell**: the **first-run setup wizard** (`lpb-config
+  setup`) walks you through it inside the container, pre-filled from
+  `LPB_LEMONADE_BASE_URL` / `LPB_LEMONADE_API_KEY` env or `lpb.conf.env`. Re-run it any time inside the
 container with `lpb-config setup --reconfigure`.
 
 ### Common commands

doc/env-vars.md

@@ -28,8 +28,12 @@ If a value from `.env` doesn't seem to apply, check shell env first:
 | `LPB_BROWSER_DIR` | `~/.lpb-stack/agent-browser` | Host dir for browser profiles & sessions |
 | `LPB_CONTAINER_NAME` | `lpb-stack` | Container name (set in `lpb.stack.env`) |
 | `LPB_IMAGE_CLI` / `LPB_IMAGE_WEB` | `ghcr.io/lpb-stack/devstack:dev-{cli,web}` | Last-resort fallback images (forks repoint these) |
+| `LPB_LEMONADE_BASE_URL` | `http://127.0.0.1:13305/v1` | Lemonade server URL — passed to the container; on a first boot (`--ssh`/`--web`) the launcher health-checks it and prompts for the real host if unreachable |
+| `LPB_LEMONADE_API_KEY` | `lemonade` | Lemonade API key — passed to the container for the first-boot setup wizard |
 | `GHCR_USERNAME` | `lpb-stack` | Registry user for pulls |
 
+(The bare `LEMONADE_BASE_URL` / `LEMONADE_API_KEY` names are also accepted on the host; the `LPB_` form wins.)
+
 ## Runtime Defaults (baked into the image via `lpb.conf.env`)
 
 | Variable | Default | Purpose |

doc/lpb-cli.md

@@ -77,6 +77,29 @@ lpb /myproject -- --thinking high            # pass any pi flag
 - **`LPB_SSH_PORT`** (default `2222`): forwarded to the container; the
   connect line (`ssh -p <port> lpb@<host>`) is printed when the server starts.
 
+### First-boot Lemonade prompt (`--ssh` / `--web`)
+
+On the **first boot of a fresh state volume** (no `~/.pi/.initialized` in
+`LPB_STATE_DIR`), detached-server modes run the container's setup
+non-interactively — so `lpb` resolves your Lemonade server on the host side
+first:
+
+1. URL from `LPB_LEMONADE_BASE_URL` / `LEMONADE_BASE_URL` env or
+   `lpb.conf.env` (default `http://127.0.0.1:13305` when unset).
+2. Health probe (`GET <url>/api/v1/models`, 3 s). Unreachable on a TTY →
+   you're offered to type the real host (re-probed until it answers or you
+   press Enter to keep the current one); reachable → silent.
+3. API key is asked with the configured value (or `lemonade`) as default.
+
+The resolved URL + key are passed to the container
+(`LPB_LEMONADE_BASE_URL` / `LPB_LEMONADE_API_KEY`), where the first-boot
+hook (`lpb-config setup --non-interactive`) writes `auth.json` + default
+model. Foreground Pi/shell modes skip the host prompt — the in-container
+interactive wizard handles it, pre-filled from the same env. Non-TTY
+(hosts/CI) and already-initialized volumes: no prompt, static passthrough
+only. Reconfigure any time inside the container with
+`lpb-config setup --reconfigure`.
+
 ## Image Selection
 
 Two image flavours are published to `ghcr.io/lpb-stack/devstack`:

doc/lpb-config.md

@@ -39,7 +39,7 @@ see [lpb-devstack reference](lpb-devstack.md).
 | Command | Description |
 |---|---|
 | `lpb-config setup` | Interactive first-run setup: lemonade provider (auth.json), default model (settings.json), lpb-memory config. Runs automatically on first boot (start.sh); idempotent — re-run with `--reconfigure` to change server/model |
-| `lpb-config setup --non-interactive` | Same, no prompts — `LEMONADE_BASE_URL` / `LEMONADE_API_KEY` env + defaults (used on TTY-less first boots) |
+| `lpb-config setup --non-interactive` | Same, no prompts — `LEMONADE_BASE_URL` / `LEMONADE_API_KEY` env + defaults. On TTY-less first boots the `lpb` launcher passes them in (first-boot prompt in `--ssh`/`--web` modes, see `lpb-cli.md`) |
 
 ### Pipeline Override
 

scripts/lpb.py

@@ -343,6 +343,10 @@ class Config:
     ssh_pubkey = ""
     ssh_password = ""
     ssh_port = os.environ.get("LPB_SSH_PORT", _conf_cfg.get("LPB_SSH_PORT", "2222"))
+    # Lemonade model server (prompted on first boot with a TTY, otherwise from
+    # env/lpb.conf.env) — passed to the container for the first-boot setup hook.
+    lemonade_base_url = ""
+    lemonade_api_key = ""
     pi_args = []  # args after "--" forwarded to pi inside container
 
 
@@ -1426,6 +1430,13 @@ def _build_run_env(mount_path: str) -> list[str]:
         f"LPB_EXA_API_KEY={os.environ.get('LPB_EXA_API_KEY', os.environ.get('EXA_API_KEY', ''))}",
         f"LPB_MAX_TOKENS_CONTEXT_RATIO={os.environ.get('LPB_MAX_TOKENS_CONTEXT_RATIO', _conf_cfg.get('LPB_MAX_TOKENS_CONTEXT_RATIO', '0.06'))}",
     ]
+    # Lemonade model server — resolved in cmd_run (step 6b): first-boot prompt
+    # on a TTY, otherwise static env/lpb.conf.env. start.sh bridges
+    # LPB_LEMONADE_* → LEMONADE_* for the plugin and the setup wizard.
+    if cfg.lemonade_base_url:
+        env_vars.append(f"LPB_LEMONADE_BASE_URL={cfg.lemonade_base_url}")
+    if cfg.lemonade_api_key:
+        env_vars.append(f"LPB_LEMONADE_API_KEY={cfg.lemonade_api_key}")
     # GHCR token for image pulls (personal account requires auth)
     ghcr_token = os.environ.get('GHCR_TOKEN') or os.environ.get('GITHUB_TOKEN') or os.environ.get('LPB_GITHUB_TOKEN', '')
     ghcr_username = os.environ.get('GHCR_USERNAME', _conf_cfg.get('GHCR_USERNAME', 'lpb-stack'))
@@ -1680,6 +1691,72 @@ def _run_cli(project_dir: str, env_vars: list[str], volumes: list[str]) -> None:
     # Container is removed (--rm), nothing to clean up
 
 
+def _bare_lemonade_url(raw: str) -> str:
+    """Normalize a lemonade URL to bare http://host:port (strip /v1, /api/v1…).
+
+    Mirrors lpb-config's _bare_base_url — the container normalizes again when
+    it reads LEMONADE_BASE_URL, so this exists only for the host-side probe.
+    """
+    url = (raw or "").strip()
+    if not url:
+        return ""
+    if not url.startswith(("http://", "https://")):
+        url = "http://" + url
+    return re.sub(r"/(api/)?v\d+/?$", "", url)
+
+
+def _url_reachable(url: str, timeout: float = 3.0) -> bool:
+    """Best-effort probe of a lemonade server (GET <bare>/api/v1/models)."""
+    bare = _bare_lemonade_url(url)
+    if not bare:
+        return False
+    try:
+        with urllib.request.urlopen(f"{bare}/api/v1/models", timeout=timeout):
+            return True
+    except Exception:
+        return False
+
+
+def _prompt_lemonade_first_boot(resolved_state: str) -> None:
+    """Resolve lemonade server URL + API key for container env passthrough.
+
+    Static resolution always applies: shell env LPB_LEMONADE_BASE_URL /
+    LEMONADE_BASE_URL, then lpb.conf.env. On a first boot (no .initialized
+    marker in the state dir) in a detached-server mode (--ssh / --web) with
+    a host TTY, the resolved URL (default http://127.0.0.1:13305 when unset)
+    is health-probed: unreachable → the user is offered the real host, and
+    the API key is asked with a default. The container's non-interactive
+    first-boot setup (start.sh → lpb-config setup) then consumes the passed
+    env vars. Foreground modes skip the host prompt — the in-container
+    interactive wizard handles it with these values pre-filled.
+    """
+    cfg.lemonade_base_url = (os.environ.get("LPB_LEMONADE_BASE_URL")
+                             or os.environ.get("LEMONADE_BASE_URL")
+                             or _conf_cfg.get("LPB_LEMONADE_BASE_URL", ""))
+    cfg.lemonade_api_key = (os.environ.get("LPB_LEMONADE_API_KEY")
+                            or os.environ.get("LEMONADE_API_KEY")
+                            or _conf_cfg.get("LPB_LEMONADE_API_KEY", ""))
+    detached_server = cfg.ssh_mode or cfg.web_mode
+    first_boot = not (Path(resolved_state) / ".pi" / ".initialized").exists()
+    if not (detached_server and first_boot and sys.stdin.isatty()):
+        return
+    default_url = "http://127.0.0.1:13305"
+    cfg.lemonade_base_url = _bare_lemonade_url(cfg.lemonade_base_url) or default_url
+    if not _url_reachable(cfg.lemonade_base_url):
+        while True:
+            warn(f"Lemonade server unreachable: {cfg.lemonade_base_url}")
+            val = input(f"  Server URL [Enter = keep {cfg.lemonade_base_url}]: ").strip()
+            if not val:
+                break
+            cfg.lemonade_base_url = _bare_lemonade_url(val)
+            if _url_reachable(cfg.lemonade_base_url):
+                break
+    done(f"Lemonade server: {cfg.lemonade_base_url}")
+    key_default = cfg.lemonade_api_key or "lemonade"
+    key = input(f"  API key [Enter = {key_default}]: ").strip()
+    cfg.lemonade_api_key = key or key_default
+
+
 def cmd_run():
     """Resolve the project, decide the mode (cli/web/shell/ssh), and launch the
     container. Foreground modes attach interactively; web/ssh run detached.
@@ -1709,6 +1786,9 @@ def cmd_run():
     os.makedirs(resolved_state, exist_ok=True)
     os.makedirs(dir_browser, exist_ok=True)
 
+    # ── 6b. Lemonade URL/key: first-boot prompt (TTY) or static passthrough ─
+    _prompt_lemonade_first_boot(resolved_state)
+
     # ── 7. Shell mode: attach to existing container (falls through to
     #    full startup when none exists; SSH mode skips this — it always
     #    does a fresh detached server) ───────────────────────────────────

scripts/test_lpb.py

@@ -7,6 +7,7 @@
   test_lpb_tags.py        — image tag selection + image resolution
   test_lpb_selfupdate.py  — lpb --update (launcher self-update)
   test_lpb_ssh.py         — SSH mode (key auto-detect, password auth)
+  test_lpb_lemonade.py    — first-boot lemonade URL/key prompt + env passthrough
   test_lpb_regression.py  — structural guards, env files, cmd_* regression
                             tests, mutation tests
 
@@ -25,6 +26,7 @@
 from test_lpb_tags import TESTS as TAG_TESTS
 from test_lpb_selfupdate import TESTS as SELFUPDATE_TESTS
 from test_lpb_ssh import TESTS as SSH_TESTS
+from test_lpb_lemonade import TESTS as LEMONADE_TESTS
 from test_lpb_regression import TESTS as REGRESSION_TESTS
 
 TESTS = [
@@ -35,6 +37,7 @@
     *TAG_TESTS,
     *SELFUPDATE_TESTS,
     *SSH_TESTS,
+    *LEMONADE_TESTS,
 ]