docs: make README product-first and harden orphan cleanup

[mohanagy]

Summary

• reframe the README around the multi-account MCP problem and the single-connector profile model
• add a practical Claude Desktop onboarding path, including Docker, credential, GUI-environment, and readiness guidance
• preserve concise links to configuration, safety, routing, secrets, OAuth, and threat-model documentation
• add a focused README product-copy contract
• fix a macOS CI reliability boundary: once a direct provider has exited, immediately force-kill its retained descendant process group instead of waiting through the normal graceful-shutdown delay
• add a deterministic regression for a SIGTERM-ignoring retained descendant

Validation

• npm test (1,030 passed; 22 expected platform skips)
• Node 20 npm run test:core (393 passed; 22 expected platform skips)
• npm run test:coverage (95.48% statements, 92.05% branches)
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package

All passed locally.

Summary by CodeRabbit

• Documentation
  • Reworked the README into a shorter, outcome-focused guide centered on single MCP connector usage and deliberate multi-account profile selection.
  • Added/streamlined a Claude Desktop quickstart (init, validate, doctor) and simplified multi-account examples and links.
  • Clarified trust/control boundaries, local operation expectations, auditing, and what the product does not replace.
• Bug Fixes
  • Improved POSIX secret-process termination behavior to avoid slower shutdown paths when the direct process has already exited.
• Tests
  • Added README “product contract” validation tests.
  • Added coverage for cleanup and timeout behavior involving stubborn retained descendant processes.

[coderabbitai]

📝 Walkthrough

Walkthrough

The README now focuses on Miftah’s single-connector, multi-account workflow, Claude Desktop setup, control boundaries, and targeted documentation. The secret runner now force-kills POSIX process groups when the direct provider exits, with regression coverage for stubborn descendants.

Changes

README product contract

Layer / File(s)	Summary
Product framing and contract validation README.md, tests/readme-product-contract.test.ts	The README establishes multi-account positioning and product boundaries, while tests assert required wording and absence of an internal term.
Onboarding and multi-account flow README.md	Claude Desktop setup now covers init, validate, and doctor, followed by a simplified multiple-profile example using one connector.
Boundaries and follow-up documentation README.md	Compatibility, OAuth limitations, secret references, routing context, profile locking, and focused documentation links are summarized.

Secret-provider descendant cleanup

Layer / File(s)	Summary
Direct-child-aware process termination src/secrets/secret-process-runner.ts	POSIX termination tracks whether the direct child exited and immediately sends SIGKILL to the process group when appropriate.
Stubborn descendant regression coverage tests/fixtures/fake-secret-provider.mjs, tests/secret-providers.test.ts	A stubborn descendant fixture and non-Windows test verify timeout handling and forceful descendant cleanup.

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

Possibly related PRs

• mohanagy/miftah#62: Both changes cover the secret-provider process execution and descendant cleanup path.

Poem

A rabbit hops through README lore,
One connector opens every door.
Stubborn child processes flee,
SIGKILL clears the process tree.
Profiles guide the account flight—
Clean paths make the burrow bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title matches the main changes: README repositioning and orphan-descendant cleanup hardening.
Description check	✅ Passed	The summary and validation sections are detailed and relevant, though the template’s security impact section is missing.

✨ 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/product-readme

---

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