feat: make setup wizard the first-use front door

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file. The format
 
 ### Changed
 
+- [#204](https://github.com/mohanagy/miftah/issues/204) Made guided setup an explicit first-use product front door: the terminal wizard now presents numbered source choices, visible setup steps, safe back/cancel handling before connection details, and current-step recovery for invalid choices; the README now places both `miftah setup` and the `miftah dashboard` browser Console ahead of the optional scripted `init` example and distinguishes the browser UI from the lower-level `console` API command. Existing local STDIO, returning provider-owned account, no-secret, no-shell, no-overwrite, OAuth ownership, import, validation, and shared CLI/Console setup boundaries are unchanged. External evaluator acceptance remains open and is not claimed.
 - [#290](https://github.com/mohanagy/miftah/issues/290) Redesigned the README as a concise product front door: first-screen fit guidance, one connector with named profiles, one safe GitHub first-success path, distinct secret/native-OAuth/upstream-owned-OAuth routes, visible client/wizard/Console choices, and progressively disclosed security, architecture, reference, and troubleshooting links. External evaluator acceptance remains open and is not claimed by this documentation change.
 
 ### Fixed

README.md

@@ -48,7 +48,7 @@ Miftah exposes management tools such as `miftah_list_profiles`, `miftah_current_
 
 ## Quick start
 
-This example creates one Claude Desktop connector with `work` and `personal` GitHub profiles. It requires Node.js 20 or newer and Docker.
+Install Miftah, then choose the terminal wizard or the browser Console. Both use the same validated setup services. The terminal wizard can start from a known connector, remote HTTPS MCP, reviewed local executable, supported browser sign-in, or one existing client entry. The browser Console provides first-run setup for a known connector or a standards-compatible remote MCP with native OAuth.
 
 ### 1. Install the current release
 
@@ -57,7 +57,31 @@ npm install -g @lubab/miftah@0.5.0
 miftah version
 ```
 
-### 2. Generate the configuration and client snippet
+### 2. Choose a human-first setup
+
+**Terminal wizard**
+
+```bash
+miftah setup
+```
+
+The wizard shows numbered choices, lets you go back before entering connection details, validates before writing, and can print client JSON for manual review.
+
+**Browser Console**
+
+```bash
+miftah dashboard
+```
+
+Keep the foreground terminal open, enter its one-time code in the local browser page, then choose **Set up an MCP**. `miftah dashboard` is the browser UI; the similarly named `miftah console` command starts the lower-level local control API.
+
+Neither path asks for a token, password, or browser cookie. Miftah does not silently edit Claude Desktop, Claude Code, Cursor, or VS Code settings.
+
+Follow the generated handoff to review one client connector, merge it into your client settings, and restart or reconnect that client.
+
+### Optional: scripted GitHub example
+
+Use `miftah init` when you want a repeatable preset command instead of either human-first flow. This example creates one Claude Desktop connector with `work` and `personal` GitHub profiles. It requires Docker.
 
 ```bash
 miftah init github --preset github --output ~/.config/miftah/github.json --client claude-desktop
@@ -67,7 +91,7 @@ Miftah creates `~/.config/miftah/github.json` and prints a Claude Desktop `mcpSe
 
 The generated profiles refer to `GITHUB_WORK_TOKEN` and `GITHUB_PERSONAL_TOKEN`. Provide least-privilege tokens through a supported [secret provider](docs/config.md#secret-providers), not as raw values in the Miftah or Claude JSON. OS keychain references use `secretref:keychain://`; 1Password references use `secretref:op://`. Claude Desktop is a GUI app and does not normally inherit variables from terminal startup files such as `~/.zshrc`.
 
-### 3. Validate before connecting the client
+#### Validate before connecting the client
 
 After those credential references are available to the process that will launch Miftah, run:
 
@@ -79,7 +103,7 @@ miftah test-profile --config ~/.config/miftah/github.json --profile work
 
 `validate` checks configuration shape. `doctor` checks redacted credential and upstream readiness. `test-profile` starts and initializes only the selected profile. None proves provider scopes or account identity beyond the evidence it actually reports.
 
-### 4. Connect and select the account
+#### Connect and select the account
 
 Merge the printed `mcpServers` entry into Claude Desktop through **Developer → Edit Config**, save, and restart Claude Desktop. Then ask:
 
@@ -118,7 +142,7 @@ On Windows, `generic`, `sentry`, and `generic-npx` are unavailable. Miftah refus
 ## Wizard, CLI, clients, and optional Console
 
 - `miftah setup` is the guided terminal wizard. It asks what you already have, collects only the metadata needed for that path, validates before writing, and never asks for a token, password, or browser cookie.
-- `miftah init` is the scripted preset path used in the quick start.
+- `miftah init` is the optional scripted preset path shown in the quick start.
 - `miftah dashboard` opens the optional foreground-only local Console for reviewed setup, profiles, health, and OAuth lifecycle work. It is not required to run Miftah.
 - Client generation can print reviewable snippets for Claude Desktop, Claude Code, Cursor, and VS Code. Miftah never silently edits their settings.
 

docs/cli.md

@@ -74,7 +74,7 @@ miftah validate --config "$HOME/Miftah configs/work wrapper.json"
 
 `generic-npx` requires `--npm-package` with exact package SemVer; `generic-docker` requires a canonical digest in `--docker-image`; `streamable-http` requires `--url` plus optional credential environment/header metadata; and one-account noninteractive `google-search-console` requires `--oauth-client-secrets-file` with an absolute path. `local-stdio` requires `--local-command` and `--accept-local-command`; it accepts repeated literal `--arg` values, optional native absolute `--cwd`, and optional `--credential-env`. Use `--arg=--flag` for a value that begins with a dash. On Windows, the local executable must be an absolute `.exe` or `.com` binary; bare commands and `.cmd`/`.bat` shims are rejected so the direct argv path never uses a command processor. On Windows, `generic`, `sentry`, and `generic-npx` are unavailable because npm's `npx` runner requires a command shell. It rejects shell executables and wrappers, URL-like commands, environment references, controls, and credential-shaped command or argument values. It writes a read-only profile, treats unknown tools as destructive, and does not launch a generic local executable during `init` or `setup`. Guided GSC setup can collect one or more named accounts, their client-secrets paths, and an explicit default profile. `--credential-env` is optional where supported. The GSC adapter prints credential/browser/identity ownership without printing a configured path. See [preset and client compatibility](presets-and-clients.md) for exact inputs, pins, provenance, and client snippets, and [provider adapters](provider-adapters.md) for the upstream-owned OAuth boundary.
 
-`--interactive` uses a wizard only when both input and output are TTYs. EOF or Ctrl-C while it is collecting initial configuration data cancels without writing a config. A bare `miftah setup` begins with `What do you already have? (connector, remote HTTPS, local executable, browser sign-in, import) [connector]`. Choose `connector` for a known connector or pinned package, `remote` for the strict generic `streamable-http` path, `local` for `local-stdio`, `browser sign-in` for a remote MCP that authenticates in the system browser, or `import` to provide one explicit absolute client JSON file and select one listed entry. Guided import renders entry names only, never source commands, arguments, headers, environment values, or credentials. It asks for variable names and safe metadata, never secret values. The generic `remote` answer does not discover authentication or call the endpoint; choose `browser sign-in` or use `miftah setup --native-oauth` only when the remote server advertises standards-based OAuth. For `local-stdio`, it asks for one argv element at a time and prints only a bounded count-based review summary before the acknowledgement; it does not echo arguments or credential values. For Google Search Console it asks for each account's profile name, optional description, and client-secrets path, then an explicit default profile. `miftah setup --verify` is an explicit opt-in to run each selected adapter's declared safe read-only check after the configuration write. It never accepts a tool name or arguments from the operator, never guesses a health command, does not auto-approve a policy confirmation, and returns only bounded status rather than provider output. The check runs only while the selected profile still matches the adapter's reviewed launch envelope; otherwise it reports a bounded unsupported status without launching the provider. If the post-write readiness prompt is cancelled, Miftah keeps the configuration, reports incomplete verification, and exits 1. A non-ready `setup --verify` result also keeps the configuration and exits 1. `init` is network-free and does not accept `--verify` or client-entry import flags. In noninteractive use, `init` creates only the config unless `--client` is supplied. `--client` prints JSON with absolute Node and compiled Miftah paths; it does not write a host config. For `claude-code` or `all`, it also prints a separate, exact management-tool `permissions.ask` fragment for manual merge into Claude Code settings; it never writes or overwrites those settings. Regenerate the snippets after moving or upgrading Miftah or changing the config path.
+`--interactive` uses a wizard only when both input and output are TTYs. EOF or Ctrl-C while it is collecting initial configuration data cancels without writing a config. A bare `miftah setup` shows a numbered **Step 1** with a known connector or pinned package, remote HTTPS endpoint, local executable, remote MCP with browser sign-in, and existing client entry. Enter a number or the matching name. **Step 2** confirms the selected path; enter `back` to return to the first step before connection details are collected, or `cancel` to exit before a configuration is written. Invalid source or confirmation input stays on the current step. Guided import renders entry names only, never source commands, arguments, headers, environment values, or credentials. It asks for variable names and safe metadata, never secret values. The generic remote path does not discover authentication or call the endpoint; choose the browser-sign-in path or use `miftah setup --native-oauth` only when the remote server advertises standards-based OAuth. For `local-stdio`, it asks for one argv element at a time and prints only a bounded count-based review summary before the acknowledgement; it does not echo arguments or credential values. For Google Search Console it asks for each account's profile name, optional description, and client-secrets path, then an explicit default profile. `miftah setup --verify` is an explicit opt-in to run each selected adapter's declared safe read-only check after the configuration write. It never accepts a tool name or arguments from the operator, never guesses a health command, does not auto-approve a policy confirmation, and returns only bounded status rather than provider output. The check runs only while the selected profile still matches the adapter's reviewed launch envelope; otherwise it reports a bounded unsupported status without launching the provider. If the post-write readiness prompt is cancelled, Miftah keeps the configuration, reports incomplete verification, and exits 1. A non-ready `setup --verify` result also keeps the configuration and exits 1. `init` is network-free and does not accept `--verify` or client-entry import flags. In noninteractive use, `init` creates only the config unless `--client` is supplied. `--client` prints JSON with absolute Node and compiled Miftah paths; it does not write a host config. For `claude-code` or `all`, it also prints a separate, exact management-tool `permissions.ask` fragment for manual merge into Claude Code settings; it never writes or overwrites those settings. Regenerate the snippets after moving or upgrading Miftah or changing the config path.
 
 `miftah setup ... --plan` validates a complete noninteractive first-configuration candidate and prints a structural, non-secret JSON plan without creating a directory, writing a file, or contacting an upstream. It includes the supplied output location, but deliberately excludes the endpoint, executable, working directory, arguments, environment names, credential references, headers, OAuth details, and secret values. `--plan` is unavailable for interactive, import, profile-addition, and native-OAuth setup because those flows have their own review or discovery boundaries.
 
@@ -84,7 +84,7 @@ For a bare interactive `connector` journey, Miftah writes a private checkpoint a
 
 For a static local account, noninteractive use requires `--profile` and `--credential-env`; the latter is an environment-variable name, never a secret value. This path accepts only a configuration with exactly one unnamed `stdio` upstream, one direct `${ENV_NAME}` credential binding in every profile, one shared destination/policy, no provider adapter, no native OAuth, and no named upstreams or other profile overrides. It atomically adds one profile that points at a different environment variable, enforces profile-switch confirmation and explicit destructive selection, and never starts the upstream or reads the credential. Remote HTTP credentials use headers rather than profile environments, so remote configurations fail closed with `ENVIRONMENT_PROFILE_ADDITION_UNSUPPORTED`. Generic `--verify` is deliberately rejected because Miftah has no declared safe probe. The durable default changes only when `--make-default` is present, so existing MCP clients still need a restart or new connection.
 
-`miftah setup <name> --import-file <absolute-json-file> --import-entry <name>` is a separate no-secret flow, not a generic client migration. The same flow is available to a first-time interactive user: run bare `miftah setup`, choose `import` at `What do you already have? (connector, remote HTTPS, local executable, browser sign-in, import) [connector]`, provide the exact file, and select one listed entry by number or exact name. The source file must be an absolute regular non-symlink file. Miftah reads it through one bounded verified handle, requires an explicitly selected entry, and never changes the source. Guided import lists safe entry names only; it does not print source command, argument, header, environment, or credential data. It accepts either a local `stdio` entry under `mcpServers` (Claude Desktop, Claude Code, or Cursor) or `servers` (VS Code) that fits its finite static launch grammar—literal executable, optional absolute working directory, and either an exact-version package-runner launch with only that runner's fixed safe prefix flags and no arguments after the package, a script path plus non-sensitive flags, or a direct executable plus non-sensitive flags—or one credential-free HTTPS remote entry. A remote import uses `url` under `mcpServers` or `servers` and must explicitly declare `type: "http"` or `"streamable-http"`. It requires HTTPS without userinfo, query, fragment, or opaque credential-shaped path segments, and does not discover OAuth or call the remote endpoint. On Windows, a local import accepts only a direct absolute `.exe` or `.com` executable; bare runners such as `npx` or `node`, and `.cmd`/`.bat` shims, are rejected rather than being dispatched through a command processor. It rejects `env`, headers, shell settings, unknown fields, environment wrappers, inline code, opaque values or assignments, unsupported remote transports, URL userinfo, opaque credential-shaped URL path segments, unpinned package references, and credential-shaped arguments. It creates a read-only default profile with unknown tool risk set to destructive and does not launch the imported program. `--verify` is rejected before publication because no reviewed provider adapter is inferred.
+`miftah setup <name> --import-file <absolute-json-file> --import-entry <name>` is a separate no-secret flow, not a generic client migration. The same flow is available to a first-time interactive user: run bare `miftah setup`, choose **Existing client entry** by number or name, confirm the path, provide the exact file, and select one listed entry by number or exact name. The source file must be an absolute regular non-symlink file. Miftah reads it through one bounded verified handle, requires an explicitly selected entry, and never changes the source. Guided import lists safe entry names only; it does not print source command, argument, header, environment, or credential data. It accepts either a local `stdio` entry under `mcpServers` (Claude Desktop, Claude Code, or Cursor) or `servers` (VS Code) that fits its finite static launch grammar—literal executable, optional absolute working directory, and either an exact-version package-runner launch with only that runner's fixed safe prefix flags and no arguments after the package, a script path plus non-sensitive flags, or a direct executable plus non-sensitive flags—or one credential-free HTTPS remote entry. A remote import uses `url` under `mcpServers` or `servers` and must explicitly declare `type: "http"` or `"streamable-http"`. It requires HTTPS without userinfo, query, fragment, or opaque credential-shaped path segments, and does not discover OAuth or call the remote endpoint. On Windows, a local import accepts only a direct absolute `.exe` or `.com` executable; bare runners such as `npx` or `node`, and `.cmd`/`.bat` shims, are rejected rather than being dispatched through a command processor. It rejects `env`, headers, shell settings, unknown fields, environment wrappers, inline code, opaque values or assignments, unsupported remote transports, URL userinfo, opaque credential-shaped URL path segments, unpinned package references, and credential-shaped arguments. It creates a read-only default profile with unknown tool risk set to destructive and does not launch the imported program. `--verify` is rejected before publication because no reviewed provider adapter is inferred.
 
 If guided import refuses a selected entry, Miftah keeps no rejected source values and writes no configuration from it. It preserves only the non-secret configuration name and output location already collected, then moves to the existing interactive manual transport setup. Re-enter either a reviewed local executable with literal arguments or a canonical HTTPS endpoint; do not copy the rejected entry wholesale. Configure credentials or OAuth separately through the upstream's documented flow and Miftah secret references. This recovery applies only to bare interactive `miftah setup`; the explicit `--import-file` and `--import-entry` command remains fail-closed with a safe error for scripts and automation.