docs: make trust controls and profile handoff discoverable

[mohanagy]

Summary

• Put Miftah credential, identity, OAuth, policy, audit, and client-handoff boundaries in one first-use README section.
• Add a no-token team-sharing pattern that explicitly distinguishes shareable configuration from local credentials, token caches, state, and journals.
• Use one consistent non-secret profile-handoff explanation in init, client import, native OAuth setup, and the local Console.

Relates to #202. The issue remains open for its external-evaluator acceptance evidence.

Security impact

• This PR does not add a credential store, secret transport, subprocess invocation, routing rule, or policy bypass.
• Generated client handoffs remain metadata-only: launcher paths and configuration paths, never credential values or OAuth token material.
• Existing secret resolution, provider-owned OAuth token-cache ownership, routing/policy enforcement, redaction, audit behavior, and fail-closed error behavior are unchanged.
• The Console and README make those existing boundaries explicit; they do not claim that configuration validation proves a credential is valid, correctly scoped, or owned by the intended account.

Validation

• Focused docs, CLI, Console, and setup contracts: 189 passed.
• npm test and npm run test:core passed during local validation.
• npm run build, npm run smoke:cli, npm run check:pack, npm run test:package, npm run lint, and npm run typecheck passed.
• An unchanged full coverage rerun on this docs-only branch hit the already tracked cross-suite startup flake in test: eliminate aggregate-suite upstream startup instability #255, outside this diff; the same base passed a full coverage run immediately before. No timeout, skip, worker, coverage, or product behavior change was made.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 37 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c04c5f5e-ec95-4001-a9e9-9062c46c218b

📥 Commits

Reviewing files that changed from the base of the PR and between 57ff943 and f1d00a0.

📒 Files selected for processing (1)

• src/cli/client-snippets.ts

📝 Walkthrough

Walkthrough

The change centralizes non-secret client handoff guidance, routes CLI outputs through a shared formatter, and documents trust boundaries and safe configuration sharing in the README, changelog, and Console UI.

Changes

Client handoff guidance

Layer / File(s)	Summary
Shared client handoff formatting src/cli/client-snippets.ts, src/cli/init.ts, src/cli/setup-client-entry-import.ts, src/cli/setup-native-oauth.ts, tests/client-snippets.test.ts, tests/init-command.test.ts	Client snippets now include reusable guidance, and CLI handoff paths consistently format guidance with generated JSON.
README trust and sharing boundaries README.md, CHANGELOG.md, tests/readme-product-contract.test.ts	Documentation defines Miftah’s control boundaries, safe secret-reference sharing, validation steps, and the related changelog entry.
Console boundary disclaimers src/console/console-assets.ts, tests/console-server.test.ts	Console copy and tests clarify credential, account, provider-token, and generated-entry limitations.

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

Possibly related PRs

• mohanagy/miftah#59: Earlier client snippet and initialization work overlaps with the updated handoff pipeline.
• mohanagy/miftah#191: Related Console client-snippet and handoff functionality.
• mohanagy/miftah#201: Overlapping README trust-boundary and product-contract documentation changes.

Poem

A rabbit hops through profiles bright,
One connector guides them all just right.
No secret crumbs are packed inside,
Trust boundaries stand open wide.
“Validate, doctor, then connect!”
Says Bun, with ears erect.

---

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
Docstring Coverage	❌ Error	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 clearly matches the main change: making trust controls and profile handoff discoverable in docs and CLI guidance.
Description check	✅ Passed	The description follows the template sections and provides solid summary, security impact, and validation details.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/202-trust-discoverability

---

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

[mohanagy]

@coderabbitai review

Addressed the walkthroughs pre-merge findings on the new head: formatClientSnippetHandoff now has a full parameter/return security contract docstring, and the PR description now includes Security impact. The focused client-snippets contract remains green. Please refresh the review against 75e26a1.

[coderabbitai]

@mohanagy: Refreshing the review against 75e26a1f97cefa548b4ca5b1ec7314ac79c7d684, including the updated handoff contract and security-impact context.

✅ 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]

@mohanagy, refreshing the review for #261 against 75e26a1ad3175bd1684292f483c6fff1230fe08f, including the updated handoff security contract and Security impact context.

✅ 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.

[mohanagy]

Merge-gate note: CodeRabbit reports a temporary 42-minute review limit on its refreshed run, so it cannot produce another full assessment. Its remaining Docstring Coverage warning is stale after this final head: both modified exported functions in src/cli/client-snippets.ts now have explicit parameter/return contracts, and the PR description Security impact check passed.\n\nException evidence: exact head f1d00a0 has all required Linux, macOS, Windows, quality, and Verify CI jobs green; CodeRabbit status is green; there are no review threads or human reviews; and a local Claude Code Opus review of origin/development...HEAD returned No actionable findings. This documents the rate-limit exception before merge; no CodeRabbit finding is being silently ignored.