Merge pull request #10 from refrakts/docs/improve-docs-usability

fix(docs): improve onboarding navigation

Author: Quantumlyy

site/pages/getting-started.mdx

@@ -3,6 +3,21 @@
 
 MBGA is a collection of React hooks for building Bitcoin apps on [Spark](https://www.spark.info/). It handles wallet connections, balance queries, payments, and more.
 
+## Choose Your Path
+
+| Goal | Best starting point |
+| --- | --- |
+| I want the fastest setup | [Scaffold a project](/installation#scaffolding) |
+| I already have a React app | Continue with the quick start below |
+| I need framework-specific setup | [Vite](/frameworks/vite) or [Next.js](/frameworks/nextjs) |
+| I am not sure which wallet integration to use | [Connector overview](/connectors#choosing-a-connector) |
+
+## Before You Begin
+
+- MBGA's React package is named `mbga`.
+- `MbgaProvider` creates and owns the TanStack Query client for you.
+- You will usually install `@mbga/connectors` alongside `mbga`, then add any extra connector peer dependencies you need.
+
 ## Quick Start
 
 ### 1. Install
@@ -25,6 +40,12 @@ yarn add mbga @mbga/connectors @tanstack/react-query
 
 ### 2. Create a Config
 
+Choose the connector that matches your app:
+
+- `xverse()` for Xverse via Sats Connect
+- `walletStandardDiscovery()` for wallets implementing the Wallet Standard
+- `spark()` for programmatic or embedded wallets via the Spark SDK
+
 ```ts
 // src/mbga.ts
 import { walletStandardDiscovery, xverse } from '@mbga/connectors'
@@ -53,6 +74,8 @@ function App() {
 }
 ```
 
+If you already have your own app providers, place `MbgaProvider` alongside them near the root of your app.
+
 ### 4. Use Hooks
 
 ```tsx
@@ -111,6 +134,7 @@ MBGA abstracts all three behind a single `sendPayment` call.
 
 ## Next Steps
 
+- [Installation](/installation#connector-specific-dependencies) — add connector peer dependencies before integrating a specific wallet
 - [Installation](/installation) — detailed setup for different connectors
 - [Connectors](/connectors/) — choose the right connector for your use case
 - [Frameworks](/frameworks/vite) — framework-specific setup guides

site/pages/index.mdx

@@ -91,6 +91,16 @@ yarn add mbga @mbga/connectors
 
 ## Overview
 
+### Start Here
+
+| If you want to... | Start here |
+| --- | --- |
+| Get a working app running as fast as possible | [Installation](/installation#scaffolding) |
+| Add MBGA to an existing React app | [Getting Started](/getting-started#quick-start) |
+| Choose the right wallet integration | [Connectors](/connectors#choosing-a-connector) |
+| Set up framework-specific wiring | [Vite](/frameworks/vite) or [Next.js](/frameworks/nextjs) |
+| Browse the API surface | [API Reference](/api/) |
+
 ```tsx
 // 1. Import modules.
 import { createConfig, sparkMainnet } from 'mbga'
@@ -127,6 +137,27 @@ mbga supports all these features out-of-the-box:
 - Framework-agnostic [core actions](/api/core-actions) for vanilla JS usage
 - TypeScript ready with [strict typing](/api/types) throughout
 
+## Common Paths
+
+### Build a wallet connection flow
+
+1. [Install MBGA](/installation)
+2. Pick a [connector](/connectors)
+3. Follow [Getting Started](/getting-started)
+4. Add a pre-built UI with [Kit](/kit) if you do not want to build the wallet UI yourself
+
+### Build a server-managed or embedded wallet app
+
+1. [Install MBGA](/installation)
+2. Use the [Spark SDK connector](/connectors/spark-sdk)
+3. Use [core actions](/api/core-actions) or React [hooks](/api/hooks)
+
+### Add Flashnet orchestration
+
+1. Set up the base wallet flow with [Getting Started](/getting-started)
+2. Add [Flashnet authentication](/flashnet/authentication)
+3. Continue with the [Flashnet docs](/flashnet)
+
 ## Community
 
 Check out the following places for more mbga-related content:

site/pages/installation.mdx

@@ -1,6 +1,18 @@
 
 # Installation
 
+## Choose an Install Path
+
+| If you want to... | Do this |
+| --- | --- |
+| Start from scratch with a ready-made app | Use [create-mbga](#scaffolding) |
+| Add MBGA to an existing React app | Install the packages below |
+| Support a specific wallet | Add the matching [connector dependency](#connector-specific-dependencies) |
+
+## What to Install
+
+Install `mbga` for the React hooks, `@mbga/connectors` for wallet integrations, and any extra connector-specific dependency your app needs.
+
 ## Package Manager
 
 :::code-group
@@ -21,10 +33,20 @@ yarn add mbga @mbga/connectors @tanstack/react-query
 
 - `mbga` — React hooks
 - `@mbga/connectors` — wallet connector implementations
-- `@tanstack/react-query` — peer dependency for caching and state management
+- `@tanstack/react-query` — peer dependency used internally by `MbgaProvider`
+
+After installing, continue with [Getting Started](/getting-started) to create your config and mount `MbgaProvider`.
 
 ## Connector-specific Dependencies
 
+Use this table if you want to confirm the extra package before reading the connector guide:
+
+| Connector | Extra package | When to use it |
+| --- | --- | --- |
+| [Sats Connect](/connectors/sats-connect) | `sats-connect` | Browser wallets such as Xverse |
+| [Spark SDK](/connectors/spark-sdk) | `@buildonspark/spark-sdk` | Programmatic, embedded, or server-managed wallets |
+| [Wallet Standard](/connectors/wallet-standard) | None | Runtime wallet discovery across compatible wallets |
+
 ### Sats Connect (Xverse)
 
 If using the [Sats Connect](/connectors/sats-connect) connector, also install `sats-connect`:
@@ -83,6 +105,8 @@ yarn create mbga
 
 This generates a ready-to-run project with MBGA pre-configured.
 
+Use this path if you want to skip manual setup and start from a working Vite + React project.
+
 ## Requirements
 
 - Node.js 18+