docs: redesign README for first use

[mohanagy]

Summary

• reduce the README from 708 lines to a 152-line product front door with first-screen fit guidance
• explain one connector with named profiles and provide one literal GitHub + Claude Desktop first-success path
• separate secret/API-key, native OAuth, and upstream-owned OAuth routes
• surface wizard, CLI, supported client snippets, and the optional Console
• move detailed security, architecture, configuration, routing, isolation, OAuth, and troubleshooting material behind tested links
• align the linked setup guide with the current five-source wizard vocabulary and add a focused CLI troubleshooting section

Why

A first-time reader could not quickly decide whether Miftah fit their multi-account MCP problem because the README had grown into a security and operations reference. This keeps the security and pre-1.0 boundaries intact while making the first read task-oriented and progressively disclosed.

TDD

The new first-use contract was added first and observed failing because the existing README parsed as 709 lines against a 260-line ceiling. The README and linked docs were then changed until the focused product and cross-document contracts passed. Critical package versions, commands, config paths, secret-reference schemes, client paths, OAuth ownership language, Windows refusal wording, and local link anchors remain contract-bound.

Validation

• npx vitest run tests/readme-product-contract.test.ts
• npm test — 1,769 passed; 33 platform/availability cases skipped
• npm run test:core — 425 passed; 26 platform/availability cases skipped
• npm run test:coverage — 95.65% statements/lines, 91.92% branches, 98.66% functions
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack — 47 files verified
• npm run test:package — 26 passed

Refs #290
Parent: #202

This PR intentionally does not close #290. The implementation and documentation contracts are complete, but the acceptance criterion requiring three external evaluators remains open; #25 and #88 also remain open for real-user validation.

Summary by CodeRabbit

• Documentation
  • Redesigned the README “product front door” for one local MCP connector with named profiles and clearer setup paths.
  • Streamlined onboarding with an explicit GitHub first-success flow, updated quick start/version guidance, and safer “what not to share” notes.
  • Clarified authentication routes (secrets, native OAuth, and upstream-owned OAuth) and added platform/environment constraints.
  • Added CLI troubleshooting guidance for missing profiles/secrets, stale durable state, and browser authorization/session issues.
  • Updated the unreleased changelog to reflect the README redesign.
• Tests
  • Strengthened README/CLI contract checks to ensure guidance and flags stay consistent and pasteable.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 953e320b-0df0-4e72-aa8c-f72f83576fd8

📥 Commits

Reviewing files that changed from the base of the PR and between 6463c39 and a60e214.

📒 Files selected for processing (2)

• docs/cli.md
• tests/readme-product-contract.test.ts

---

📝 Walkthrough

Walkthrough

Miftah’s README was redesigned as a product-first onboarding guide with named profiles, a GitHub quick-start path, authentication routing, safety boundaries, and deeper documentation links. CLI troubleshooting and README contract tests were updated to match the new guidance.

Changes

README onboarding and documentation

Layer / File(s)	Summary
Product front door and quick start README.md	Introduces named profiles, consolidates duplicate client entries, and documents a versioned GitHub setup and connection flow.
Setup paths and operational guidance README.md, docs/cli.md, docs/presets-and-clients.md	Clarifies authentication ownership, client and safety boundaries, setup choices, Windows constraints, and troubleshooting procedures.
Documentation contract validation tests/readme-product-contract.test.ts, tests/release-version.test.ts, CHANGELOG.md	Updates README command, flag, version, link, routing, and changelog assertions for the redesigned documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• mohanagy/miftah#202 — Covers the broader README onboarding and first-use discoverability goals implemented here.

Possibly related PRs

• mohanagy/miftah#103 — Similar README product-first rewrite and contract-test updates.
• mohanagy/miftah#201 — Related task-oriented onboarding rewrite and README contract assertions.
• mohanagy/miftah#235 — Overlapping setup-path guidance distinguishing remote, OAuth, and native OAuth.

Poem

A bunny hops through profiles bright,
One connector keeps the path in sight.
GitHub work and personal play,
Safe secrets guide the way.
Docs bloom where troubleshooting starts—
Miftah leads with open hearts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: redesigning the README for first-time use.
Description check	✅ Passed	The description is detailed and mostly follows the template, but it omits the Security impact section and checklist-style validation.
Linked Issues check	✅ Passed	The docs and contract updates cover the README redesign, named profiles, OAuth paths, client discovery, and troubleshooting requested in #290.
Out of Scope Changes check	✅ Passed	The changes stay within the README/docs/test/changelog scope for the documentation redesign and add no unrelated feature work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-290-readme-first-use

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/cli.md`:
- Line 199: Update the validation command in the CLI documentation to pass the
exact configuration file used by the client, including a clearly replaceable
absolute path after --config. Keep the surrounding validation guidance
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5e6d29cc-c98e-4c43-97ce-eaba5932ceb5

📥 Commits

Reviewing files that changed from the base of the PR and between 3edc746 and 6463c39.

📒 Files selected for processing (6)

• CHANGELOG.md
• README.md
• docs/cli.md
• docs/presets-and-clients.md
• tests/readme-product-contract.test.ts
• tests/release-version.test.ts