design: first-run provider setup flow — how should the CLI populate .env.kontext?

[tumberger]

Context

When a user runs kontext start for the first time in a project, there's no .env.kontext file. The CLI needs to figure out which providers to resolve credentials for. Today this file is manually created — the user should never have to do that.

Possible flows

Option A: Auto-populate from backend, no prompt

1. CLI fetches the org's configured providers from the backend
2. Writes .env.kontext with all of them (or a sensible default subset)
3. Resolves credentials — skips any that aren't connected yet
4. User commits the file, team shares it

Pro: Zero friction, instant start.
Con: May include providers the project doesn't need. File becomes org-level, not project-level.

Option B: Auto-populate from backend, ask the user to confirm

1. CLI fetches available providers
2. Shows them: "These providers are available: GitHub, Linear, Slack. Which ones does this project need?"
3. User selects, CLI writes .env.kontext

Pro: Project-specific. Clean .env.kontext.
Con: Extra step on first run. Interactive prompt may not work in all environments (CI, etc.).

Option C: Fetch connected providers only

1. CLI fetches only providers the current user has already connected in the dashboard
2. Writes .env.kontext with those
3. No prompt needed — if you connected it, you probably want it

Pro: Simple, no prompt. Only includes things the user actively set up.
Con: Different users may get different .env.kontext files. Doesn't capture project requirements.

Option D: Start with a hardcoded default set

1. CLI writes .env.kontext with a default set (e.g. GitHub, Linear) without calling the backend
2. User edits if they need more or fewer

Pro: Simplest to implement. Works offline.
Con: Doesn't scale, not personalized.

Option E: Hybrid — auto-populate, then let the user edit via kontext providers

1. First run: auto-populate from backend (option A or C) silently
2. Provide a kontext providers command to add/remove/list providers interactively later
3. kontext start always reads the file as-is

Pro: Fast first run + escape hatch for customization.
Con: Two commands to learn.

Open questions

• Should .env.kontext be project-scoped (committed) or user-scoped (gitignored)?
• If committed, how do we handle different users having different providers connected?
• Should the CLI auto-create the file or require explicit kontext init?
• What about CI environments where there's no interactive prompt?
• How does the env var naming work? The backend knows the provider handle (github) but the env var name (GITHUB_TOKEN) is a project concern — who decides that mapping?

[tumberger]

My take: server-side catalog + local selection

The provider catalog should come from the backend, not be hardcoded or user-authored. The admin configures which providers are available for the org/workspace in the dashboard — that's the source of truth. The CLI fetches that catalog and the developer picks which ones the project needs.

This rules out Option D (hardcoded defaults) — it doesn't scale and diverges from what the org actually has configured.

Option B vs Option E

I think Option B (fetch + interactive prompt on first run) is the right starting point:

1. kontext start — no .env.kontext exists
2. CLI fetches available providers from backend (what the admin configured)
3. Shows them with connection status per user: "Available providers: GitHub (connected), Linear (connected), Slack (not connected)"
4. Developer selects which ones this project needs
5. CLI writes .env.kontext, developer commits it

This keeps the catalog centralized (admin controls what's available) while the selection is project-scoped (developer controls what's needed). The .env.kontext file becomes a committed, shared declaration of project requirements — not a copy of the org's full provider list.

Option E (add a kontext providers command) is a nice follow-up but shouldn't block the first-run experience. If we nail Option B, the providers command becomes a convenience for editing the template later — not a requirement.

Open question: what about providers that aren't connected yet?

If the developer selects a provider they haven't connected, the CLI should handle that inline — open the dashboard connect flow, wait for completion, then continue. This ties into #29.