docs: add wallet provider compatibility matrix and fallback routing #76

[Danielkallala]

Overview

This PR documents the wallet provider compatibility matrix and fallback routing order for Project Vyn. Contributors need to know which wallets work in which environments and what happens when a provider is unavailable.

Related Issue

Closes #76

Changes

• [ADD] \docs/wallets.md\

  • Compatibility matrix for all 7 supported wallets (Freighter, Albedo, xBull, Lobstr, Hana, Rabet, Privy) with desktop/mobile support, auth method, and Kit module.
  • Fallback routing order: Privy session -> Kit modal -> Saved provider -> Freighter default.
  • Unavailable provider behaviour (Freighter missing, no extensions on mobile, modal dismissed, Privy not ready).
  • Environment detection via \isMobileBrowser().
  • Provider persistence storage keys.
  • Architecture diagrams for connect and sign flows.
  • Unsupported combinations and instructions for adding new wallets.

• [MODIFY] \README.md\

  • Updated intro to list all wallet providers (was only Freighter/Albedo).
  • Expanded wallet requirement to list all supported options with link to the new docs.
  • Added \docs/wallets.md\ link in the Architecture section.

Verification Results

All documentation cross-referenced against actual source code:

• \src/lib/stellarWalletsKit.ts\ — 6 Kit modules confirmed (Freighter, Albedo, xBull, Lobstr, Hana, Rabet)
• \src/lib/mobileWalletConnectors.ts\ — \isMobileBrowser(), \connectWallet(), \signTransactionXdr(), \getSavedProvider()\
• \src/lib/privyBridge.ts\ — Privy session handling confirmed
• \src/wallet/StellarWalletAdapter.ts\ — Adapter delegation confirmed

No code changes — pure documentation, no build/lint breakage.

Acceptance Criteria

Criteria	Status
PR documents active wallet options	✅ All 7 wallets documented with compatibility matrix
Fallback behaviour is clear	✅ 4-step fallback order documented with diagrams
Reviewer can tell which wallet to use per device type	✅ Desktop/mobile column in matrix
Unsupported combinations noted	✅ Dedicated section listing 5 unsupported combos
Documentation matches actual code paths	✅ Cross-referenced against 6 source files

[vercel]

@Danielkallala is attempting to deploy a commit to the alankcr1-6443's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Danielkallala Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits