fix(cli): enter setup on a requires-model config and hint zero auth login

Two residual first-run gaps after the catalog model-defaulting fix:

- An active provider whose model has NO catalog default to fall back on
  (custom openai-/anthropic-compatible endpoints) still bricked bare
  `zero` and `zero setup` — the exact commands that could have repaired
  the config. Tag that resolve failure with ErrProviderRequiresModel and
  extend the interactive TUI's fixable-error fallback (previously only
  ErrNoActiveProvider) to drop into the setup wizard for it. The sentinel
  is attached via a message-preserving wrapper (multi-target Unwrap), so
  headless commands (zero config / zero exec) print the exact actionable
  text unchanged and every other resolve error stays fatal.

- `zero login` / `zero logout` don't exist (it's `zero auth login`);
  first-run users try them and got only "unknown command" (reported in
  the wild). The unknown-command error now answers: did you mean
  "zero auth login"? Unrelated unknown commands get no suggestion.

Tests: the sentinel comes from a REAL Resolve over a real config file
(message-prefix asserted, no key leak); the TUI fallback is red-green
(reverting the condition reproduces the exact brick with the old error);
the existing no-active-provider fallback and other-errors-stay-fatal
tests still pass; login/logout hint with a no-false-positive check.

Author: gnanam1990

internal/cli/app.go

@@ -402,6 +402,14 @@ func runWithDeps(args []string, stdout io.Writer, stderr io.Writer, deps appDeps
 		if _, err := fmt.Fprintf(stderr, "unknown command %q\n", args[0]); err != nil {
 			return 1
 		}
+		// First-run users reach for `zero login`/`zero logout` (reported in the
+		// wild); point them at the real command instead of a bare usage pointer.
+		switch strings.ToLower(args[0]) {
+		case "login", "logout":
+			if _, err := fmt.Fprintf(stderr, "did you mean %q?\n", "zero auth "+strings.ToLower(args[0])); err != nil {
+				return 1
+			}
+		}
 		if _, err := fmt.Fprintln(stderr, "Run zero --help for usage."); err != nil {
 			return 1
 		}
@@ -530,11 +538,17 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 
 	resolved, err := deps.resolveConfig(workspaceRoot, config.Overrides{})
 	if err != nil {
-		// A resolve failure caused solely by a missing/unresolvable active provider
-		// is not fatal for the interactive TUI: drop into the setup wizard with an
-		// empty config so the user can onboard, instead of exiting with an error.
-		// Any other error (malformed JSON, directory conflict, etc.) is still fatal.
-		if !errors.Is(err, config.ErrNoActiveProvider) {
+		// A resolve failure the setup wizard can FIX is not fatal for the
+		// interactive TUI: drop into the wizard with an empty config so the user
+		// can onboard/repair, instead of exiting with an error they can only fix
+		// by hand-editing config.json. That covers a missing/unresolvable active
+		// provider and an active provider without a model (custom endpoints have
+		// no catalog default) — previously the second shape bricked bare `zero`
+		// and `zero setup`, the exact commands that could have fixed it. Any
+		// other error (malformed JSON, directory conflict, etc.) is still fatal,
+		// and headless commands (zero config / zero exec) still fail with the
+		// actionable message.
+		if !errors.Is(err, config.ErrNoActiveProvider) && !errors.Is(err, config.ErrProviderRequiresModel) {
 			return writeAppError(stderr, err.Error(), 1)
 		}
 		resolved = config.ResolvedConfig{}

internal/cli/app_test.go

@@ -1476,3 +1476,75 @@ func TestRunThemeFlagRejectsBadValue(t *testing.T) {
 		t.Fatalf("expected a clear --theme error, got %q", stderr.String())
 	}
 }
+
+// A custom endpoint saved without a model previously bricked bare `zero` and
+// `zero setup` — the exact commands that could have fixed it (the resolve
+// error escaped before the wizard could open). The interactive TUI now treats
+// the requires-model failure as "needs onboarding", same as a missing active
+// provider. The error comes from a REAL Resolve over a real config file, so
+// this exercises the production sentinel wrapping, not a hand-built error.
+func TestRunNoArgsEntersSetupWhenActiveProviderMissesModel(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	cwd := t.TempDir()
+	setCLIUserConfigRoot(t)
+	brokenConfig := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(brokenConfig, []byte(`{
+		"activeProvider": "gw",
+		"providers": [{"name": "gw", "provider_kind": "openai-compatible", "baseURL": "https://gw.example/v1", "apiKey": "sk-x"}]
+	}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	launched := false
+	var launchedOptions tui.Options
+
+	exitCode := runWithDeps([]string{}, &stdout, &stderr, appDeps{
+		getwd: func() (string, error) { return cwd, nil },
+		resolveConfig: func(string, config.Overrides) (config.ResolvedConfig, error) {
+			return config.Resolve(config.ResolveOptions{UserConfigPath: brokenConfig, Env: map[string]string{}})
+		},
+		newProvider: func(config.ProviderProfile) (zeroruntime.Provider, error) {
+			t.Fatal("newProvider must not be called without a resolved provider")
+			return nil, nil
+		},
+		userConfigPath: func() (string, error) { return filepath.Join(t.TempDir(), "zero", "config.json"), nil },
+		registerMCPTools: func(context.Context, *tools.Registry, config.MCPConfig, mcp.RegisterOptions) (mcpToolRuntime, error) {
+			return noopMCPRuntime{}, nil
+		},
+		runTUI: func(_ context.Context, options tui.Options) int {
+			launched = true
+			launchedOptions = options
+			return 0
+		},
+	})
+
+	if exitCode != 0 {
+		t.Fatalf("exit code = %d, want 0 (setup TUI launched), stderr=%q", exitCode, stderr.String())
+	}
+	if !launched {
+		t.Fatal("TUI was not launched; a fixable requires-model config must fall into setup, not exit fatally")
+	}
+	if !launchedOptions.Setup.Visible || !launchedOptions.Setup.Required {
+		t.Fatalf("Setup = %#v, want visible required setup", launchedOptions.Setup)
+	}
+}
+
+// `zero login`/`zero logout` don't exist (it's `zero auth login`); first-run
+// users try them (reported in the wild), so the unknown-command error points at
+// the real command.
+func TestRunUnknownLoginSuggestsAuthLogin(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	exitCode := runWithDeps([]string{"login"}, &stdout, &stderr, appDeps{})
+	if exitCode != 2 {
+		t.Fatalf("exit = %d, want 2 (unknown command)", exitCode)
+	}
+	if !strings.Contains(stderr.String(), `"zero auth login"`) {
+		t.Fatalf("stderr = %q, want a zero auth login suggestion", stderr.String())
+	}
+	// An unrelated unknown command gets no misleading suggestion.
+	stderr.Reset()
+	runWithDeps([]string{"frobnicate"}, &stdout, &stderr, appDeps{})
+	if strings.Contains(stderr.String(), "did you mean") {
+		t.Fatalf("stderr = %q, unrelated commands must not get the auth hint", stderr.String())
+	}
+}

internal/config/resolver.go

@@ -20,6 +20,26 @@ import (
 // onboarding" (drop into the setup wizard) rather than a fatal config error.
 var ErrNoActiveProvider = errors.New("no active provider configured")
 
+// ErrProviderRequiresModel marks a resolve failure caused solely by the active
+// provider missing a model with no catalog default to fall back on (custom
+// openai-/anthropic-compatible endpoints — Zero cannot guess a gateway's model).
+// Like ErrNoActiveProvider, the interactive TUI treats it as "needs onboarding"
+// and drops into the setup wizard so the user can fix it; headless commands
+// (zero config, zero exec) still fail with the actionable message.
+var ErrProviderRequiresModel = errors.New("provider requires model")
+
+// setupFixableError tags an error with a sentinel for errors.Is WITHOUT
+// changing its message: the sentinel's own text must not prefix what the user
+// sees (the wrapped message is already complete and actionable).
+type setupFixableError struct {
+	err      error
+	sentinel error
+}
+
+func (e *setupFixableError) Error() string { return e.err.Error() }
+
+func (e *setupFixableError) Unwrap() []error { return []error{e.err, e.sentinel} }
+
 // defaultMaxTurns is the per-run tool-turn budget when none is configured. 30 was
 // too low for real multi-step agentic work (agents ran out mid-task before reaching
 // later steps); 50 matches the old "deep" preset. Raise per-session with /turns.
@@ -808,7 +828,10 @@ func normalizeProvidersWithOptions(providers []ProviderProfile, activeName strin
 		return nil, ProviderProfile{}, fmt.Errorf("%w: active provider %q not found", ErrNoActiveProvider, activeName)
 	}
 	if active.Model == "" {
-		return nil, ProviderProfile{}, providerError(active, "provider %s requires model — add \"model\" to its entry in config.json, or re-run: zero setup <catalog-id> --model <model>", active.Name)
+		return nil, ProviderProfile{}, &setupFixableError{
+			err:      providerError(active, "provider %s requires model — add \"model\" to its entry in config.json, or re-run: zero setup <catalog-id> --model <model>", active.Name),
+			sentinel: ErrProviderRequiresModel,
+		}
 	}
 
 	return normalized, active, nil

internal/config/resolver_test.go

@@ -1624,3 +1624,28 @@ func TestNormalizeWithoutModelDefaultsStillRequiresGoogleModel(t *testing.T) {
 		t.Fatalf("error = %q, want an actionable config.json hint", err.Error())
 	}
 }
+
+// The residual requires-model failure (custom endpoint, no catalog default)
+// must be tagged setup-fixable WITHOUT changing its message: the interactive
+// TUI matches the sentinel to drop into the wizard, while headless commands
+// print the exact actionable text.
+func TestResolveRequiresModelErrorIsSetupFixable(t *testing.T) {
+	path := writeConfig(t, `{
+		"activeProvider": "gw",
+		"providers": [{"name": "gw", "provider_kind": "openai-compatible", "baseURL": "https://gw.example/v1", "apiKey": "sk-x"}]
+	}`)
+	_, err := Resolve(ResolveOptions{UserConfigPath: path, Env: map[string]string{}})
+	if err == nil {
+		t.Fatal("expected requires-model error for a custom endpoint without model")
+	}
+	if !errors.Is(err, ErrProviderRequiresModel) {
+		t.Fatalf("error = %v, want errors.Is(err, ErrProviderRequiresModel)", err)
+	}
+	// The sentinel must NOT prefix the user-facing message.
+	if !strings.HasPrefix(err.Error(), "provider gw requires model") {
+		t.Fatalf("message = %q, want it to start with the provider error, not the sentinel text", err.Error())
+	}
+	if strings.Contains(err.Error(), "sk-x") {
+		t.Fatalf("error leaked API key: %q", err.Error())
+	}
+}