docs: improve README developer experience (#105)

* docs: overhaul main README for developer experience

- Rewrite tagline to be clear and jargon-free
- Add "Why Framework-kit?" value proposition section
- Add install instructions
- Fix incorrect function name (createSolanaClient → createClient)
- Add context and comments to quickstart code
- Simplify package descriptions
- Add Next.js example and 'use client' note
- Add "Learn more" section with documentation links

Fixes #99, #100, #101, #102, #103

* chore: add changeset for README improvements

---------

Co-authored-by: guibibeau <[email protected]>

Author: resourcefulmind

.changeset/readme-dx-improvements.md

@@ -0,0 +1,6 @@
+---
+"@solana/client": patch
+"@solana/react-hooks": patch
+---
+
+Improve main README documentation with clearer quickstart guide and better developer experience

README.md

@@ -23,28 +23,50 @@
 </p>
 
 <p align="center">
-Framework for Solana dApps: evolving multi-framework client core (React-first today) that orchestrates wallets, transactions, and reactive freshness-aware data flows out of the box.
+React hooks for Solana. Connect wallets, fetch balances, and send transactions with minimal setup.
 </p>
 
+## Why Framework-kit?
+
+Building Solana dApps usually means wiring together RPC connections, wallet adapters, and state management yourself. Framework-kit handles this for you:
+
+- **One provider, many hooks** — Wrap your app once with `SolanaProvider`, then use hooks anywhere
+- **Wallet connection built-in** — `useWalletConnection` handles discovery, connection, and disconnection
+- **Automatic data refresh** — Balances and account data stay in sync without manual refetching
+- **Common operations simplified** — `useSolTransfer`, `useSplToken`, and `useTransactionPool` for transfers and custom transactions
+- **TypeScript-first** — Full type inference out of the box
+
 ## Packages
 
-- [`@solana/client`](packages/client/README.md) – headless Solana client with transaction helpers, moniker-based endpoint helpers, and wallet orchestration.
-- [`@solana/react-hooks`](packages/react-hooks/README.md) – React bindings, providers, and UI helpers powered by the client.
+- [`@solana/client`](packages/client/README.md) – Core library for wallet connection, transactions, and RPC. Works with any framework or standalone.
+- [`@solana/react-hooks`](packages/react-hooks/README.md) – React hooks and provider. Wrap your app once, then use hooks like `useBalance` and `useSolTransfer`.
 
-## Example
-- [`@solana/example-vite-react`](examples/vite-react/README.md) – Vite/Tailwind demo showcasing the hooks in action.
+## Examples
+- [`@solana/example-vite-react`](examples/vite-react/README.md) – Vite + Tailwind demo
+- [`@solana/example-nextjs`](examples/nextjs/README.md) – Next.js (App Router) demo
+
+## Install
+
+```bash
+npm install @solana/client @solana/react-hooks
+```
 
 ## React quick start
 
+Add this to your main App file (e.g., `App.tsx`). You'll need a Solana wallet extension like [Phantom](https://phantom.app/) installed in your browser.
+
 ```tsx
-import { createClient } from "@solana/client";
+import { autoDiscover, createClient } from "@solana/client";
 import { SolanaProvider, useWalletConnection } from "@solana/react-hooks";
 
+// Create a client pointing to Solana devnet
 const client = createClient({
   endpoint: "https://api.devnet.solana.com",
+  walletConnectors: autoDiscover(), // Finds installed wallet extensions
 });
 
 function WalletButtons() {
+  // This hook gives you everything you need for wallet connection
   const { connectors, connect, connecting } = useWalletConnection();
   return (
     <>
@@ -69,3 +91,12 @@ export function App() {
   );
 }
 ```
+
+Run your app and you should see buttons for each detected wallet. Click one to connect.
+
+> **Next.js note:** Components using these hooks must be marked with `'use client'` at the top of the file.
+
+## Learn more
+
+- [Full hooks documentation](packages/react-hooks/README.md) — all available hooks and options
+- [Client API](packages/client/README.md) — use the client without React