docs: redesign README for first use

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+### Changed
+
+- [#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.
+
 ## [0.5.0] - 2026-07-28
 
 ### Added

docs/cli.md

@@ -191,3 +191,27 @@ miftah audit-verify --config "$HOME/Miftah configs/work wrapper.json" --json
 `audit-export` is deliberately explicit: it creates a new output and refuses an existing destination. It runs redaction again and strips stored `arguments` by default, even if the journal was configured to record them. `--include-arguments` opts in to the stored values after redaction; it cannot reconstruct arguments that were never recorded. The command is local-only and does not upload telemetry or start an upstream.
 
 `audit-verify` reports a safe first broken segment/record/reason and never writes a raw record, hash, or absolute path. Hash chaining provides local tamper evidence, not a signature or a remote immutable audit trail; keep required evidence in an independently protected destination.
+
+## Troubleshooting
+
+### `DEFAULT_PROFILE_NOT_FOUND`
+
+For the README GitHub path, run `miftah validate --config ~/.config/miftah/github.json` with the exact configuration file passed to the client. Confirm that `defaultProfile` names an existing profile. Regenerate a reviewed preset instead of guessing at nested JSON when the configuration shape is unclear.
+
+### `SECRET_ENV_MISSING` after exporting a variable
+
+A GUI MCP client usually does not inherit terminal startup files such as `~/.zshrc`. Make the variable available to the process that launches the client, or use a configured dotenv, keychain, 1Password, or reviewed local secret-provider reference. Do not put the raw value in Miftah or client JSON.
+
+For the README GitHub path, confirm the exact generated file with:
+
+```sh
+miftah doctor --config ~/.config/miftah/github.json
+```
+
+### The dashboard changed configuration but the client still uses old state
+
+Miftah does not replace an already-running MCP session after a configuration, OAuth, or durable-profile change. Save the reviewed change, then restart or reconnect the MCP client.
+
+### Browser authorization opened in the wrong environment
+
+Run `miftah dashboard`, `miftah auth connect`, or `miftah auth reauth` on the machine and user session that owns the local browser and OS vault. In headless automation, use the command's non-interactive mode so a required browser flow fails with `OAUTH_INTERACTIVE_REQUIRED` instead of opening unexpectedly.

docs/presets-and-clients.md

@@ -69,7 +69,7 @@ Without `--interactive`, `init` creates only a configuration unless `--client` i
 
 `--interactive` is available only when both input and output are real TTYs. EOF or Ctrl-C cancels before the configuration write. The wizard asks only for a name, an outcome-first source answer (`remote` or `local`) or catalog connector name, safe preset metadata (variable names, URLs, header metadata, pins), output location, and client selection. For `local-stdio`, it asks for one literal argv item at a time and gives a count-only review summary before explicit acknowledgement. It never asks for or echoes a secret value.
 
-`miftah setup [name]` is the dedicated guided command. It uses that same TTY-only wizard and safe preset options, with interactivity required by the command instead of supplied as `--interactive`. At its first question, choose `remote sign-in` when the selected remote MCP opens a browser to authenticate you; Miftah then uses the existing endpoint-first standards-based OAuth discovery flow before it writes anything. Choose `new` for the normal catalog question, where `remote` selects the strict `streamable-http` path and `local` selects `local-stdio`; catalog names remain accepted. The plain remote path does not discover OAuth or call the upstream. Keep `miftah setup --native-oauth` for a scripted or repeatable standards-based OAuth setup.
+`miftah setup [name]` is the dedicated guided command. It uses that same TTY-only wizard and safe preset options, with interactivity required by the command instead of supplied as `--interactive`. Its first question is `What do you already have? (connector, remote HTTPS, local executable, browser sign-in, import) [connector]`. Choose `connector` for a known connector or exact-pinned package, `remote` for an HTTPS endpoint with no authentication or a documented static header, `local` for a reviewed executable and literal argument array, `browser sign-in` for endpoint-first standards-based OAuth discovery, or `import` for one explicitly selected supported client entry. The plain remote and import paths do not discover OAuth or call the upstream. Keep `miftah setup --native-oauth` for a scripted or repeatable standards-based OAuth setup.
 
 For one-account noninteractive `google-search-console` setup, `--oauth-client-secrets-file` is required and is written only to the generated profile environment. Guided `miftah setup` asks for one or more named accounts, their client-secrets paths, and an explicit default; it generates a separate upstream-owned `GSC_CONFIG_DIR` for each generated configuration file and profile. To add another account later, use `miftah setup --add-profile --config <file>` with a new `--profile` and `--oauth-client-secrets-file`; the selected configuration must remain wholly within the reviewed adapter boundary and every existing state directory must already be distinct. The safe adapter summary printed by `init` does not echo a configured client-secrets path. The printed client snippets use absolute paths to the Node executable and compiled Miftah CLI so GUI clients do not depend on `PATH`. Regenerate them after moving or upgrading Miftah, or after changing the configuration path. Copy generated JSON as JSON; do not hand-edit the command into a shell string.