docs: explain Miftah 0.5 features and workflows (#40)

[mohanagy]

What changed

• added an owner-readable guide to what Miftah 0.5 contains and how to use each user-facing workflow
• linked that guide from the README first screen for existing Miftah users
• distinguished the actual 0.5 delta from native OAuth and Console capabilities that first shipped in 0.4
• mapped guided setup, no-write plans, resume/discard, client-entry import, Google Search Console multi-account onboarding, profile maintenance, authentication ownership, Console usage, upgrade validation, and remaining limitations to literal commands and deeper existing documentation
• added a focused documentation contract that binds every documented command and flag to generated production CLI help, validates links and paste safety, and prevents OAuth/external-validation overclaims

Why

Issue #40 is a broad roadmap checklist, but it does not give a package owner or user a fast answer to two basic questions: what exactly changed in 0.5, and how do I use it? The new guide provides that product-level orientation without duplicating the full CLI, OAuth, adapter, Console, security, or changelog references.

User impact

An existing 0.4 user can now identify the 0.5 additions in about a minute and copy the correct starting command for each workflow. A new user can distinguish API-key/secret setup, native OAuth, and upstream-owned OAuth without being told that Miftah supports every MCP server or provider.

Refs #40

TDD

The focused contract was added first and failed in five places because the guide, README entry point, feature map, command paths, and changelog record did not exist. The smallest documentation change then made all six guide contracts pass.

Validation

• focused README/release/docs contracts: 29 passed
• npm test: 1,776 passed / 33 skipped
• npm run test:core: 425 passed / 26 skipped
• npm run test:coverage: 1,776 passed / 33 skipped; 95.65% statements, 91.93% branches, 98.66% functions, 95.65% lines
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack: 48 files
• npm run test:package: 26 passed

Remaining issue #40 gates

This PR intentionally does not close #40. External multi-account and returning-user validation remain open in #25 and #88, and the roadmap still has other acceptance items that require their own real evidence.

Summary by CodeRabbit

• Documentation

  • Added a comprehensive Miftah 0.5 guide covering guided setup, resumable plans, profile management, Google Search Console onboarding, authentication options, and the local Console.
  • Documented upgrade guidance, validation steps, reliability and security considerations, and current limitations.
  • Updated the README and changelog with links and release information.

• Tests

  • Added validation to ensure documented commands, options, links, and release details remain accurate and consistent with the CLI.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a Miftah 0.5 feature and usage guide covering setup, profiles, authentication, Console usage, upgrades, and limitations. README and changelog references point to the guide, while contract tests validate documented commands, flags, links, and release metadata.

Changes

Miftah 0.5 owner guide

Layer / File(s)	Summary
Setup and import guidance docs/whats-new-in-0.5.md	Documents guided setup, preview mode, resumable checkpoints, draft disposal, and single-client import behavior.
Profiles, authentication, and Console docs/whats-new-in-0.5.md	Describes multi-account profiles, profile lifecycle commands, authentication ownership boundaries, and the optional local dashboard.
Release references and guide contract validation README.md, CHANGELOG.md, tests/v050-feature-guide-contract.test.ts	Links to the guide from project documentation and validates documented commands, flags, links, content, and version alignment.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• [Product] Make trust controls and multi-account onboarding discoverable #202 — Directly covers the owner-facing 0.5 onboarding, profile, OAuth-boundary, Console, and validation documentation.
• [Docs] Redesign README for a first-time Miftah user #290 — Also updates README onboarding guidance and links readers to related setup documentation.
• [Epic] Optional local Miftah Console and standards-based OAuth control plane #78 — Tracks the broader Console, OAuth, and profile-management roadmap described by the guide.

Possibly related PRs

• mohanagy/miftah#201 — Adds similar documentation contract validation for documented CLI commands and flags.
• mohanagy/miftah#249 — Implements a related profile command that the guide’s CLI validation must recognize.
• mohanagy/miftah#252 — Closely relates to the documented guided setup and client-entry import flow.

Poem

A bunny reads the guide at dawn,
With setup paths neatly drawn.
Profiles hop from name to name,
OAuth keeps its proper frame.
Tests check each command just right—
Miftah’s 0.5 shines bright!

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Linked Issues check	❌ Error	The PR documents 0.5 workflows, but it does not implement the core local multi-account broker requirements in #40.	Either implement the missing broker capabilities or scope this issue to docs-only work; the roadmap items still need product code.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the docs-focused 0.5 guide and workflow update.
Description check	✅ Passed	The description covers what changed, why, user impact, TDD, and validation, with only minor template mismatches.
Out of Scope Changes check	✅ Passed	The changes stay within docs and tests for the 0.5 guide, README, and changelog, with no unrelated code changes.
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 docs/issue-40-v050-feature-guide

---

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

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[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 `@docs/whats-new-in-0.5.md`:
- Around line 10-12: Update the “complete multi-account Google Search Console
onboarding path” wording in the 0.5.0 summary and the corresponding later claim
to describe the flow as implemented or reviewed but pending external validation,
avoiding any implication of full production readiness.

In `@tests/v050-feature-guide-contract.test.ts`:
- Around line 121-129: Update the “keeps every local guide link resolvable” test
to validate URL fragments in addition to target files. Preserve external-link
handling, but replace the path-only existence check with GFM-compatible Markdown
anchor validation (or equivalent heading-anchor lookup) so links such as
cli.md#missing-section fail when the referenced heading is absent.

🪄 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: 5069035c-2356-4a7c-867f-4d58ed1f8faa

📥 Commits

Reviewing files that changed from the base of the PR and between 36bcab5 and 3ba4f77.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• docs/whats-new-in-0.5.md
• tests/v050-feature-guide-contract.test.ts

[mohanagy]

Review follow-up on exact head 2c1f51dfd69e8092033fe6a03d0d3012438c1f86:

• both CodeRabbit inline findings from the prior head are addressed and replied to: GSC readiness is qualified as implemented with external validation still in progress, and local Markdown fragments are now validated with the real OAuth support-matrix link exercising the contract
• the earlier independent findings are also fixed: import/--plan incompatibility, manual provider revocation, and conditional audit recording
• focused docs contracts pass 30/30; lint, typecheck, and diff checks are clean
• an independent exact-head review found no blocking issues and verified all five corrections against production/docs boundaries

CodeRabbit's incremental review of the new commits is currently rate-limited under its Fair Usage policy (the bot reported a 38-minute wait). This is recorded rather than represented as a new approval. The prior CodeRabbit change request is stale to 3ba4f77; its two inline findings are resolved on the current head.

Dismissed as stale to 3ba4f77. Both findings are resolved on exact head 2c1f51d, both review threads are resolved and CodeRabbit acknowledged each fix. Its incremental exact-head re-review was Fair Usage rate-limited, so this dismissal is not represented as bot approval; independent exact-head review found no blockers. See PR comment #294 (comment).