First-run setup wizard skipped on Windows when API key is already in env

[jonathanpopham]

Summary

On Windows, the first-time install setup wizard appears to be skipped (or rendered too fast to interact with) when the user already has a Supermodel API key in their environment. Reported by a customer: their terminal "blew through" the wizard and they never saw the prompts — including the prompt to exclude .graph.* sidecar files from VCS.

Reported behavior

Customer "Elm" did a fresh npm install -g @supermodeltools/cli on Windows. On first invocation, the expected setup wizard (which normally walks through API key entry, ignore-file setup, etc.) did not appear, or scrolled past so fast it was non-interactive. They had a Supermodel API key already set in their environment.

Expected behavior

Even when a valid API key is detected in env, the user should still be walked through (or at minimum shown) the remaining first-run setup steps — particularly the .graph.* ignore-file prompt, which is unrelated to auth.

Hypothesis

The wizard likely short-circuits the entire flow when SUPERMODEL_API_KEY (or equivalent) is already present, instead of skipping just the auth step and continuing with the remaining setup steps.

Repro (suspected)

1. On a fresh Windows machine, set SUPERMODEL_API_KEY in env before installing.
2. npm install -g @supermodeltools/cli
3. Run supermodel <something> for the first time.
4. Observe: setup wizard either doesn't appear or scrolls through non-interactively; .graph.* files are not added to .gitignore.

Needs confirmation on a clean Windows VM.

Suggested fix direction

• Decouple the auth step from the rest of the first-run wizard — env-detected key should skip auth-prompts only, not the whole flow.
• If the wizard is meant to be one-shot and silent when env is pre-configured, surface a one-line summary of what was auto-configured and what was skipped, with a supermodel setup command to re-run interactively.

[coderabbitai]

🔗 Related PRs

#48 - feat: interactive setup wizard with file mode onboarding [merged]
#49 - Add first-run detection and install-time setup wizard [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[jonathanpopham]

Trace results — corrected diagnosis

Traced the install/run path. The original hypothesis (wizard short-circuits when env key present) is wrong. The actual cause is more fundamental:

The setup wizard is never auto-invoked on first run. It's only available as an explicit supermodel setup command.

Code path

cmd/root.go:45-60 (PersistentPreRunE):

cfg, err := config.Load()
// ...
if cfg.APIKey == "" {
    fmt.Fprintln(os.Stderr, "Run 'supermodel setup' to get started.")
    os.Exit(1)
}
return nil

internal/config/config.go:112:

if key := os.Getenv("SUPERMODEL_API_KEY"); key != "" {
    c.APIKey = key
}

So when a user has SUPERMODEL_API_KEY already set in their environment:

1. config.Load() populates cfg.APIKey from env
2. The empty-key guard passes silently
3. RunE falls straight through to shards.Watch(...) — no wizard, no gitignore prompt, no hook prompt, no shard-mode prompt, no awareness any of those steps exist

What Elm actually saw

Not "wizard scrolled past too fast" — the wizard never ran at all. He went directly into watch mode on first invocation.

What the wizard does cover

Reviewed internal/setup/wizard.go — the wizard itself handles auth, repo detection, agent hook install, and shard mode toggle correctly. It does NOT have a separate .graph.* ignore prompt though — gitignore is added automatically inside the shard-mode flow (line 148-150). That's worth noting in case the customer expected a prompt that was never going to appear regardless.

Suggested fix direction (revised)

• Detect first-run-without-setup state and auto-prompt. E.g. check for a marker (config file existence, ~/.supermodel/.setup-complete, etc.) and run the wizard the first time supermodel is invoked, even when env key is present.
• OR print a one-liner on every run-without-config that says "run `supermodel setup` to enable agent hook + gitignore" — at least surfaces the option.
• Decide intentionally: should env-key-only users get a fully-silent install (current behavior, friendly to CI/automation) or a one-time interactive nudge (better for new humans like Elm)?