Document the wallet integration and Stellar transaction flow for contributors

[greatest0fallt1me]

Description

The wallet layer is non-trivial and undocumented: constants/wallet-kits.constant.ts exposes a client-only getKit() that initializes StellarWalletsKit (defaulting to Freighter, allowAllModules), hooks/useWallet.hook.ts wraps it for connectWallet/disconnectWallet/signTransaction, and context/WalletContext.tsx persists state in localStorage and reconnects on mount. The top commented-out block in useWallet.hook.ts even shows an older, abandoned approach. This issue produces a contributor-facing guide so new developers can use the wallet hooks correctly and understand the supported wallets and network config.

Requirements and context

• Add docs/WALLET.md documenting: the supported wallet IDs surfaced in useWallet.hook.ts (Freighter, LOBSTR, XBull, Albedo, Rabet), the getKit() SSR guard, the connect/disconnect/sign API and their {success, ...} return shapes, and the localStorage persistence/reconnect behavior of WalletContext.
• Document the network configuration path (lib/config.ts stellar.network and NEXT_PUBLIC_STELLAR_NETWORK) and note the current hardcoded WalletNetwork.TESTNET in signTransaction as a known limitation.
• Include a minimal usage snippet showing a component consuming useWallet.
• Non-functional: all symbols/paths referenced must exist; remove confusion by explaining that the leading commented-out block in useWallet.hook.ts is dead code; link the doc from docs/README.md.
• Do not document submit/broadcast as implemented (it is not) — describe it as a follow-up.

Acceptance criteria

• docs/WALLET.md documents supported wallets, the kit SSR guard, and the connect/disconnect/sign API with return shapes.
• Persistence/reconnect behavior of WalletContext is described accurately.
• Network config and the hardcoded testnet passphrase limitation are documented.
• A working useWallet usage snippet is included.
• The doc is linked from docs/README.md and references only existing symbols/paths.
• Submit/broadcast is described as not-yet-implemented.

Suggested execution

1. Fork the repo and create a branch — git checkout -b docs/wallet-integration.

2. Implement changes — add docs/WALLET.md; update docs/README.md.

3. Write/extend tests — docs need no unit tests; verify the example snippet type-checks conceptually against hooks/useWallet.hook.ts. (Code in this repo is tested with Jest + React Testing Library via pnpm.)

4. Test and commit —

pnpm install
pnpm lint
pnpm build

Example commit message

docs(wallet): document the wallet hooks, supported wallets, and network config

Guidelines

• No coverage change for docs; ensure every referenced symbol/path is verified against the source.
• Keep the snippet accurate and accessible; explicitly flag the dead commented code and the unimplemented broadcast step.
• Timeframe: 96 hours.

[ReinaMaze]

GM Maintainer, can I be assigned to this issue? I’ve reviewed the requirements and can document the wallet integration flow, supported wallets, network configuration, and usage of the wallet hooks while ensuring all referenced paths and symbols are accurate.