refactor(setup): unified initial setup wizard for all modes

The first-boot configuration was three fragmented, mode-dependent
mechanisms: a host prompt (ssh/web only), an in-container wizard
(first boot only, TTY-dependent) and one-shot env passthrough. Errors
were swallowed (start.sh '||' + .initialized touched anyway), a 401 on
the keyless /models probe killed non-interactive setup even when the
key was correct, and nothing ever validated credentials before pi ran.

Now there is ONE wizard (localpibox.setup) for every mode:

  lpb setup   host-side wizard: config repo -> server URL -> API key
              -> default model -> lpb-memory (full memory wizard: mode,
              transport, background model, limits). Every step is
              validated with live HTTP probes; failures loop with the
              raw error visible ('a' = start anyway, flagged; 'q' =
              abort, nothing written). Writes auth.json/settings.json/
              lpb-memory-config.json directly into the state dir, so
              configuration is persisted BEFORE first use.
  lpb doctor  read-only checklist (repo, settings, creds, live probe,
              runtime, image).
  preflight   before EVERY fresh start (cli/shell/ssh/web): healthy
              provider -> silent; missing/broken + TTY -> wizard;
              non-TTY -> env passthrough + visible note. Validation is
              live, so a moved server / changed key re-offers the wizard
              instead of going silently stale.
  lpb-config setup/check/memory setup delegate to the same wizard;
  start.sh keeps only the infra bootstrap and a non-interactive
  fallback with a prominent failure banner + every-boot reminder.

Also: probe is auth-aware (Bearer key sent; 401/403 reported as
'key rejected', distinct from unreachable); wizard no longer crashes
on non-integer memory limits; memory wizard prefills CURRENT values;
self-update now ships lpb-config/lpb-devstack/localpibox; docs +
tests updated (80/80 lpb family, all 15 localpibox suites).

Author: lpb-docs

README.md

@@ -25,28 +25,33 @@ lpb --web /path/to/your/project  # VSCodium editor (background, prints a URL)
 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. 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`.
+On the **first run** — in every mode (`lpb`, `--shell`, `--ssh`, `--web`) —
+`lpb` checks the model-provider state (stored credentials + a live probe of
+the Lemonade server). If it's missing or broken and you're on a terminal,
+the **setup wizard** runs before the container starts: config repo, server
+URL, API key, default model (from the server's live model list) and
+lpb-memory config — every step validated, with errors shown and re-asked
+until they're right. The configuration is written straight into the state
+volume, so it's persisted **before first use**; the launch summary ends with
+a model status line.
+
+- **Non-TTY** (hosts/CI) or `lpb --non-interactive`: no wizard — the env
+  (`LPB_LEMONADE_BASE_URL` / `LPB_LEMONADE_API_KEY` / `lpb.conf.env`) is
+  passed through and the container runs a non-interactive fallback.
+- Re-run any time (all modes): `lpb setup` (wizard) and `lpb doctor`
+  (read-only validation). Inside the container the same wizard is
+  `lpb-config setup` (and `lpb-config check`).
 
 ### Common commands
 
 ```bash
 lpb --stop       # stop the container
 lpb --logs       # stream container logs
 lpb --update     # update the launcher + pull the latest image
+lpb setup        # initial setup wizard (server, key, model, memory)
+lpb doctor       # validate the installation (read-only)
 lpb --remove     # stop, remove container + state dirs
-lpb --config     # show config file location
+lpb --config     # show config file location + model status
 lpb --help       # full usage
 ```
 
@@ -156,6 +161,8 @@ podman exec -it lpb-stack bash
 | `pi update --extensions` | Update unpinned packages (tag-pinned packages are skipped — move a pin with `pi install git:github.com/lpb-stack/<repo>@<new-tag>`) |
 | `lpb-devstack validate` | Validate stack alignment (repos, branches, pins) |
 | `lpb-devstack bump` | Bump VERSION + commit (the release trigger for CI build/tag) |
+| `lpb-config setup` | Initial setup wizard (provider, model, memory) — the in-container twin of `lpb setup` |
+| `lpb-config check` | Validate the installation (read-only) |
 | `lpb-config memory setup` | Interactive wizard for the memory extension |
 
 Inside the Pi TUI: `/login <provider>`, `/model`, `/settings` (thinking
@@ -236,11 +243,12 @@ publishes versioned tags plus the `:dev-*`, `:main-*`, `:latest-*` floats.
 Let `lpb` resolve the tag (`lpb --tag dev|main|<version>`), or pull e.g.
 `ghcr.io/lpb-stack/devstack:latest-web` explicitly.
 
-### No model available / login fails
+### No model available / setup failed
 
-The Lemonade server on the host must be running before Pi can list models:
-start it, then in the Pi TUI run `/lemonade refresh` (or `/login lemonade`
-again).
+The Lemonade server on the host must be running before the setup wizard can
+validate it: start it, then re-run `lpb setup` (or `lpb doctor` to see what
+is wrong). Inside a running session, `/lemonade refresh` re-syncs the model
+list once the provider is configured.
 
 ### Port already in use
 

VERSION

@@ -1 +1 @@
-0.0.63-lpb-dev
+0.0.64-lpb-dev

doc/config-repo.md

@@ -44,8 +44,12 @@ The settings file is **template-driven**, not git-tracked:
 
 1. **Template**: `settings.json.template` ships in the config repo with
    `__LPB_VERSION__` placeholders
-2. **Boot**: `start.sh` generates `settings.json` by replacing placeholders
-3. **No model preconfigured**: user runs `/login lemonade` to set up the provider
+2. **Boot**: the setup wizard (`lpb setup` / `lpb-config setup`) renders
+   `settings.json` by replacing placeholders (fallback: `start.sh` via
+   `lpb-config render`)
+3. **Model configured interactively**: the setup wizard writes
+   `defaultProvider` + `defaultModel` with live validation (no `/login`
+   needed for lemonade)
 4. **Persistence**: `settings.json` lives on the host volume — it survives
    container rebuilds
 5. **Validation**: `lpb-devstack validate` checks settings.json pins match

doc/lpb-cli.md

@@ -14,6 +14,8 @@ Installs (no sudo required) into `~/.local/bin`:
 
 - `lpb` — bash wrapper
 - `lpb.py` — Python engine
+- `lpb-config`, `lpb-devstack` + the shared `localpibox` package
+  (the setup wizard behind `lpb setup` / `lpb doctor`)
 
 …and copies the stack config files (`lpb.stack.env`, `lpb.conf.env`,
 `VERSION`) to `~/.lpb-stack/devstack/`. Make sure `~/.local/bin` is on your
@@ -31,13 +33,15 @@ Installs (no sudo required) into `~/.local/bin`:
 | `lpb --stop` | Stop the container |
 | `lpb --remove` | Stop + remove container + state dirs |
 | `lpb --logs` | Stream container logs |
-| `lpb --update` | Self-update the launcher + pull the latest image(s) |
-| `lpb --config` | Show config file location |
+| `lpb --update` | Self-update the launcher + stack tools + pull the latest image(s) |
+| `lpb setup` | Run the **initial setup wizard** (server, key, model, memory) — any time, all modes |
+| `lpb doctor` | Validate the installation (read-only checklist) |
+| `lpb --config` | Show config file location + model provider status |
 | `lpb --version` | Show installed launcher version |
 | `lpb --help` | Full usage |
 
 Positional aliases (no `--` needed): `lpb logs`, `lpb stop`, `lpb update`,
-`lpb remove`, `lpb config`, `lpb version`, `lpb help`.
+`lpb remove`, `lpb config`, `lpb setup`, `lpb doctor`, `lpb version`, `lpb help`.
 
 ### Pi passthrough
 
@@ -77,27 +81,42 @@ 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
+### Initial setup — one wizard for all modes
+
+Before the **first container start — in every mode (cli, shell, ssh, web)** —
+`lpb` validates the model-provider configuration. The provider state is
+checked live (stored credentials in `LPB_STATE_DIR/agent/auth.json` + a real
+HTTP probe of the Lemonade server), not a one-shot first-boot flag:
+
+- **healthy** → silent; the stored URL/key are passed to the container.
+- **missing or broken + TTY** → the **setup wizard** runs (config repo →
+  server URL → API key → default model → lpb-memory config). Every step is
+  validated live (real HTTP probes) and failures loop back with the raw
+  error visible; `a` continues anyway (flagged), `q` aborts (nothing is
+  written, no container starts). The wizard writes `auth.json`,
+  `settings.json` and `lpb-memory-config.json` directly into the state dir,
+  so the configuration is **persisted before the first use**.
+- **missing or broken + non-TTY** (or `lpb --non-interactive`) → env
+  passthrough (`LPB_LEMONADE_BASE_URL` / `LPB_LEMONADE_API_KEY` / `lpb.conf.env`)
+  with a visible note; the container runs a non-interactive fallback.
+
+Because validation is live, a server that moves or a key that changes is
+detected on the next start and re-offers the wizard — configuration is never
+silently stale. The launch summary always ends with a model status line
+(✓ provider / ⚠ fix with `lpb setup`).
+
+On-demand commands (any mode, any time):
+
+- `lpb setup` — run the wizard interactively (the way to correct a bad
+  configuration; current values are pre-filled).
+- `lpb doctor` — read-only checklist: config repo, rendered config, provider
+  credentials, live server probe, container runtime, image.
+
+Inside the container the same wizard is available as `lpb-config setup`
+(and `lpb-config check` for the checklist); `start.sh` runs it
+non-interactively as a fallback on boots where the host wizard did not run,
+and a missing provider is reported in the container logs on **every boot**
+until fixed — not swallowed. Reconfigure any time with
 `lpb-config setup --reconfigure`.
 
 ## Image Selection

doc/lpb-config.md

@@ -38,8 +38,9 @@ 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. On TTY-less first boots the `lpb` launcher passes them in (first-boot prompt in `--ssh`/`--web` modes, see `lpb-cli.md`) |
+| `lpb-config setup` | The **same wizard** as `lpb setup` on the host: config repo, lemonade provider (auth.json), default model (settings.json), lpb-memory config. Every step is validated live (HTTP probes); failures loop with the error visible. Re-run any time to correct a bad configuration — current values are pre-filled. `--reconfigure` forces a re-run |
+| `lpb-config setup --non-interactive` | Same, no prompts — `LEMONADE_BASE_URL` / `LEMONADE_API_KEY` env + defaults. First failure aborts with a precise error and writes nothing. This is the `start.sh` fallback for boots where the host wizard did not run |
+| `lpb-config check` | Validate the installation (read-only checklist: config repo, settings, credentials, live server probe) — the in-container twin of `lpb doctor` |
 
 ### Pipeline Override
 
@@ -52,8 +53,12 @@ regardless of pipeline.
 Settings.json is **template-driven**, not git-tracked:
 
 1. Config repo ships `settings.json.template` with `__LPB_VERSION__` placeholders
-2. First boot: `start.sh` generates `settings.json` (replaces placeholders)
-3. No model/provider preconfigured — user runs `/login lemonade`
+2. Before the first start, the setup wizard (`lpb setup` on the host, or
+   `lpb-config setup` in a shell) renders `settings.json` and writes the
+   lemonade provider + default model — `start.sh` re-renders on first boot
+   as a fallback (`lpb-config render`)
+3. Model/provider are configured interactively with live validation — see
+   the First-Run Setup section above (no `/login` needed for lemonade)
 4. Pin sync: `lpb-devstack workspace sync-pins` (main pipeline reads
    stable version from devstack `origin/main`)
 5. `lpb-devstack validate` checks pins match the current stack version
@@ -65,11 +70,12 @@ Example pin: `git:github.com/lpb-stack/pi-subagents@0.0.57-lpb-dev`
 
 Same template-driven pattern:
 
-1. First boot: `start.sh` copies `lpb-memory-config.json.template` → config
-   (or `lpb-config setup` configures it interactively during the first-run
-   wizard, pre-filling the model override with the selected default model)
-2. No model override — uses the main model until user configures
-3. Tune: `lpb-config memory setup` (interactive wizard)
+1. The setup wizard configures it (mode, transport, background model,
+   context limits) — pre-filling the model override with the selected
+   default model; `start.sh` falls back to a plain template copy when the
+   wizard did not run
+2. Non-interactive mode uses the template + the default-model override
+3. Tune any time: `lpb-config memory setup` (same wizard step, standalone)
 4. Review: `lpb-config memory show`
 
 ## Quick Reference
@@ -93,4 +99,8 @@ lpb-config align
 # Check / configure the memory extension
 lpb-config memory show
 lpb-config memory setup
+
+# Run / validate the initial setup
+lpb-config setup
+lpb-config check
 ```

scripts/install.sh

@@ -49,7 +49,7 @@ for tool in lpb-config lpb-devstack; do
     chmod +x "${INSTALL_DIR}/${tool}"
 done
 mkdir -p "${CONFIG_DIR}/localpibox/stack"
-for f in __init__.py cli.py env.py log.py run.py; do
+for f in __init__.py cli.py env.py log.py run.py setup.py; do
     curl -fsSL "https://raw.githubusercontent.com/${OWNER_REPO}/main/scripts/localpibox/${f}" -o "${CONFIG_DIR}/localpibox/${f}"
 done
 for f in __init__.py gitutil.py repos.py version.py workspace.py validate.py release.py; do
@@ -109,6 +109,8 @@ echo "  lpb --logs                        — View container logs"
 echo "  lpb --remove                      — Remove everything"
 echo ""
 echo "Stack tools:"
+echo "  lpb setup          — Initial setup wizard (server, key, model, memory)"
+echo "  lpb doctor         — Validate the installation"
 echo "  lpb-config status | update | reset | memory setup   — config repo (container/host)"
 echo "  lpb-devstack bump | tag-repos | workspace | validate | release — DevOps"
 echo ""