docs(wallet): add docs/WALLET_INTEGRATION.md for useWallet and Freighter client

docs/ARCHITECTURE.md

@@ -26,7 +26,7 @@ graph TD
 ### Context Responsibilities
 
 1. **`SettingsProvider`**: Manages global user preferences (theme mode, network, address display) and application settings (toast toggles and auto-dismiss timing). It must sit high in the tree because it reads from `localStorage` and applies the data-theme immediately.
-2. **`WalletProvider`**: Manages Stellar wallet connection state, exposed address, and connect/disconnect functionality. Depends on `SettingsProvider` for network preferences.
+2. **`WalletProvider`**: Manages Stellar wallet connection state, exposed address, and connect/disconnect functionality. Depends on `SettingsProvider` for network preferences. See [Wallet Integration](./WALLET_INTEGRATION.md) for more details.
 3. **`ToastProvider`**: Exposes `addToast` and `removeToast` functions for global notifications. **Must be placed inside `SettingsProvider`**, because the toast component reads `toastsEnabled` and `autoDismiss` preferences via `useSettings()` to calculate timeout bounds and global mute states.
 
 ### The Route Table & Layout Shell

docs/README.md

@@ -52,42 +52,48 @@ This directory contains comprehensive design specifications and implementation g
    - Color, spacing, radius, typography, and motion scales
    - Guidance for replacing one-off hex values in components
 
-7. **[Motion Guidelines](./motion-guidelines.md)**
+8. **[Motion Guidelines](./motion-guidelines.md)**
    - Motion token strategy and reduced-motion defaults
    - Best practices for animation and transitions
    - Implementation examples for UI micro-interactions
 
-8. **[Figma Design Specs](./FIGMA_DESIGN_SPECS.md)**
+9. **[Figma Design Specs](./FIGMA_DESIGN_SPECS.md)**
    - Visual design specifications
    - Color palette and design tokens
    - Layout measurements and spacing
    - Animation specifications
    - Responsive breakpoints
    - Component organization structure
 
-9. **[Implementation Examples](./IMPLEMENTATION_EXAMPLES.md)**
-   - Practical code examples for each page
-   - Reusable hooks and patterns
-   - Testing examples
-   - Accessibility guidelines
-   - Performance considerations
+10. **[Implementation Examples](./IMPLEMENTATION_EXAMPLES.md)**
+    - Practical code examples for each page
+    - Reusable hooks and patterns
+    - Testing examples
+    - Accessibility guidelines
+    - Performance considerations
 
-10. **[Mobile Navigation Pattern](./mobile-navigation-pattern.md)** ⭐ NEW
+11. **[Mobile Navigation Pattern](./mobile-navigation-pattern.md)** ⭐ NEW
     - Hybrid responsive navigation (hamburger mobile + horizontal desktop)
     - Complete implementation guide with code examples
     - Accessibility requirements (WCAG 2.1 AA)
     - Testing guide and troubleshooting
     - [Decision Matrix](./mobile-navigation-DECISION.md) | [Reconnaissance Report](./mobile-nav-RECON.md) | [Figma Rules](./figma-nav-rules.md)
 
-11. **[Architecture Overview](./ARCHITECTURE.md)** ⭐ NEW
+12. **[Architecture Overview](./ARCHITECTURE.md)** ⭐ NEW
     - Provider tree and routing architecture
     - Context responsibilities
     - Theming flow and mock data boundaries
 
-12. **[Keyboard Interactions Contract](./keyboard-interactions.md)** ⭐ NEW
-    - Developer-facing matrix of every interactive component and its expected keyboard behavior
-    - Covers `ConfirmDialog`, `TierLadder`, `Banner`, `Toggle`, `AddressInput`, skip-link, and navigation
-    - Focus-restore contract and checklist for new interactive components
+13. [Keyboard Interactions Contract](./keyboard-interactions.md) ⭐ NEW
+
+- Developer-facing matrix of every interactive component and its expected keyboard behavior
+- Covers `ConfirmDialog`, `TierLadder`, `Banner`, `Toggle`, `AddressInput`, skip-link, and navigation
+- Focus-restore contract and checklist for new interactive components
+
+13. [Wallet Integration](./WALLET_INTEGRATION.md) ⭐ NEW
+    - `useWallet` API documentation
+    - Connection state machine and UX contract for connection/network states
+    - Usage guide and network mismatch handling
 
 ### Quick Start
 

docs/WALLET_INTEGRATION.md

@@ -1,7 +1,80 @@
 # Wallet Integration
 
-Credence reads the connected Freighter account through `useWallet()` and compares its reported
-network against the app setting stored in `SettingsContext`.
+Credence reads the connected Freighter account through the `useWallet()` hook, which acts as the primary interface for Freighter interactions. This layer handles wallet state management, connection logic, and network alignment.
+
+## `useWallet` Hook API
+
+The `useWallet()` hook is the centralized source of truth for the wallet connection.
+
+```typescript
+export interface UseWalletState {
+  /** Connected Stellar public key, or empty when disconnected. */
+  address: string
+  /** True when a wallet address is available. */
+  isConnected: boolean
+  /** True while a connect request is in flight. */
+  isConnecting: boolean
+  /** Last connection error, if any (not_installed, rejected, network_mismatch, unknown). */
+  error: WalletError | null
+  /** Request Freighter access and store the returned public key. */
+  connect: () => Promise<void>
+  /** Clear the local wallet session. */
+  disconnect: () => void
+  /** Freighter network reported by the wallet, or null when unavailable. */
+  network: CredenceNetwork | null
+}
+```
+
+## Connection State Machine
+
+The wallet connection follows a strict state transition flow to ensure consistency.
+
+```text
+[Disconnected]
+      |
+      | connect() called
+      V
+ [Connecting] ----------------> [Connected]
+      |                             |
+      | failure                     | disconnect() or external logout
+      V                             V
+   [Error] ----------------> [Disconnected]
+(not_installed, rejected,
+ network_mismatch, unknown)
+```
+
+## UX Contract
+
+### 1. Connection Gating
+
+Action surfaces (e.g., "Create Bond", "Attest") MUST check `isConnected`. If `false`, the UI must surface the `ConnectWalletModal`.
+
+### 2. Not Installed
+
+If `error.code === 'not_installed'`, display a call-to-action urging the user to install the Freighter extension.
+
+### 3. Network Mismatch
+
+The app compares the wallet-reported network with the application's `network` setting.
+
+- Use `src/hooks/useNetworkMismatch.ts` to detect disparities.
+- Components must block primary actions if a mismatch exists and display a warning banner prompting the user to switch networks.
+
+## Consuming the Hook
+
+```tsx
+import { useWallet } from '../context/WalletContext'
+
+function ActionButton() {
+  const { isConnected, connect, address } = useWallet()
+
+  if (!isConnected) {
+    return <button onClick={connect}>Connect Wallet</button>
+  }
+
+  return <div>Connected: {address}</div>
+}
+```
 
 ## Network mismatch guard