docs: turn README into a complete first-use guide

[mohanagy]

Summary

• turns the README into a task-oriented onboarding guide from installation through profile selection
• explains preset and generic MCP setup, native versus upstream-owned OAuth, dashboard lifecycle, diagnostics, audit, policy, routing, secrets, and identity
• validates README links and current v3 configuration migration guidance with focused documentation contracts

Validation

• npm test
• npm run test:core
• npm run test:coverage
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package

Closes #200

Summary by CodeRabbit

• Documentation

  • Reworked the README into a task-oriented first-use guide with setup paths, GitHub/Claude Desktop onboarding, MCP configuration, OAuth guidance, everyday commands, troubleshooting, and task-based navigation.
  • Added visual setup guidance and clarified Miftah’s purpose, supported workflows, secrets, policies, routing, and identity controls.
  • Updated configuration documentation for the v3 contract, migration guidance, supported secret sources, and validation rules.
  • Added changelog notes identifying v3 as current while preserving v1/v2 migration support.

• Tests

  • Expanded documentation checks to validate links, commands, configuration guidance, presets, and management tools against the product’s supported options.

[coderabbitai]

📝 Walkthrough

Walkthrough

README.md is reworked into a task-oriented first-use guide covering setup, authentication, profiles, OAuth, operations, troubleshooting, and task-based links. Configuration docs align with v3, and contract tests validate documented commands, links, catalogs, anchors, and examples.

Changes

README onboarding and setup

Layer / File(s)	Summary
Setup paths and first-use flow README.md	Adds setup-path guidance and a complete GitHub with Claude Desktop onboarding flow, including initialization, generated configuration, validation, credential sources, and profile selection.
Authentication and operational reference README.md	Documents generic MCP onboarding, multi-profile configuration, OAuth ownership, everyday commands, secrets, policy, routing, identity, troubleshooting, and task-oriented links.

Configuration and validation

Layer / File(s)	Summary
Configuration and release guidance docs/config.md, CHANGELOG.md	Documents v3 configuration, migration behavior, built-in secret sources, redaction compatibility, and the related changelog entries.
README and documentation contract tests tests/readme-product-contract.test.ts	Validates README journeys, links, anchors, CLI commands and flags, catalog identifiers, generated profiles, configuration guidance, secret grammar, and changelog content.

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

Possibly related PRs

• mohanagy/miftah#59: Related README and configuration contract checks for onboarding and v3 guidance.
• mohanagy/miftah#103: Related README rewrite and product-contract test expansion.

Poem

A rabbit reads the setup trail,
With profiles tucked beneath each veil.
OAuth paths and secrets align,
V3 signs bright on every line.
Tests hop through links, commands, and lore—
“Miftah is ready!” squeaks the door.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The README now covers onboarding paths, multi-profile setup, OAuth choices, dashboard behavior, and validation docs as requested.
Out of Scope Changes check	✅ Passed	The changes stay focused on documentation and contract tests tied to the README rewrite, with no clear unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title concisely captures the primary change: making the README a first-use guide.
Description check	✅ Passed	The description covers the main change and validation steps, though it omits the Security impact section and the template's checklist format.

✨ 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 docs/200-readme-first-use

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@README.md`:
- Around line 263-275: Replace the shell-unsafe oauthconn:<uuid> placeholders
throughout the README command sequence with a pasteable placeholder such as
oauthconn:UUID_FROM_PLAN, or define and reuse a shell variable for the generated
connection ID in the commands.
- Around line 357-359: Update the troubleshooting command in the
SECRET_ENV_MISSING section to pass the same ~/.config/miftah/github.json
configuration path created by the documented first-use flow via --config,
ensuring miftah doctor checks the edited configuration.

🪄 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: f9b36812-6783-4349-a9ed-b42fcbb3ba75

📥 Commits

Reviewing files that changed from the base of the PR and between 1ec8621 and 81f9e2b.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• docs/config.md
• tests/readme-product-contract.test.ts