diff --git a/README.md b/README.md
index d8e0227..dbb2405 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,55 @@
-# @lukso/up-provider
+# up-provider
 
-Client and server connector for UPProvider.
+The up-provider allows dApps to function as mini-apps and allows parent applications to one-click-connect
+to your mini-app using the up-provider.
+
+Mini-apps are dApps loaded in iframes in the context of other applications.
+
+This package also contains the server connector for parent applications (See on the end)
+
+## Installation
+
+```bash
+npm install @lukso/up-provider
+```
 
 ## Grid Widget side of provider
 
 Client side (for example inside of a grid widget) setup
 
-### Using viem
+### Using with viem
 
 ```ts
 import { createClientUPProvider } from '@lukso/up-provider'
-import { createWalletClient, custom } from 'viem'
+import { createWalletClient, createPublicClient, custom } from 'viem'
 import { lukso } from 'viem/chains'
 
+// Construct the up-provider
 const provider = createClientUPProvider()
+
+// Create public client if you need direct connection to RPC
 const publicClient = createPublicClient({
   chain: lukso,
   transport: http(),
 })
+
+// Create wallet client to connect to provider
 const walletClient = createWalletClient({
   chain: lukso,
   transport: custom(provider),
 })
 ```
 
-### Using web3.js
+### Using with web3.js
 
 ```ts
 import { createClientUPProvider } from '@lukso/up-provider';
 import Web3, { type EthExecutionAPI, type SupportedProviders } from 'web3';
+
+// Create the up-provider
 const provider = createClientUPProvider();
+
+// Wrap provider into web3 for usage.
 const web3 = new Web3(provider as SupportedProviders<EthExecutionAPI>);
 ```
 
@@ -38,31 +58,55 @@ const web3 = new Web3(provider as SupportedProviders<EthExecutionAPI>);
 ```ts
 import { createClientUPProvider } from '@lukso/up-provider'
 import { type Eip1193Provider, ethers } from 'ethers'
+
+// Create the up-provider
 const provider = createClientUPProvider()
+
+// Wrap provider into ethers for usage.
 const browserProvider = new ethers.BrowserProvider(upProvider as unknown as Eip1193Provider)
 ```
 
-### Finding Accounts and Chains
+### Accounts and Chains
 
-The grid widget up-provider mirrors the chain and accounts provided by the parent page's
-provider and configuration. When the grid widget connects it can call eth_accounts
-to get a list of accounts. By default the accounts[0] will represent the user's address
-but will initially return '0x0*' meaning that the grid widget does not yet have permissions
-to connect to the extension. Once the user clicks the connect button above the widget
-a "accountsChanged" event will trigger to supply the user with the native connection
-the page is connected to. accounts[1] will represent the address of the owner
-of the grid displayed on screen. If the user is looking at their own grid it's probably
-an indication to disabled some buttons. For example on a "Donation" type widget it's not
-useful to send funds yto yourself.
+The up-provider gives your the chain and accounts that the parent page's supports.
 
-Most of the time the condition for "it's ok to send transactions would be"
+#### Accounts
 
-```js
-const accountConnected = accounts.length > 0 && contextAccounts.length > 0 && chainId === 42;
+As the mini-app can NOT force `eth_requestAccounts`, you need to listen to the `accountsChanged` event
+to see when a user of the parent app chose to connect to your mini-app. You can then call `eth_accounts` to get a list of accounts that can execute transactions.
+
+```ts
+provider.on('accountsChanged', (_accounts: `0x${string}`[]) => {
+  // Update your interface to show that the user is connected and enable your transaction buttons
+})
+
+// Returns a list of allowed accounts
+provider.allowedAccounts
+//> ['0x1234...']
 ```
 
+#### Context accounts
+
+A parent page can also provide you with a context account. This are one or more accounts,
+that are relevant for the context in which the mini-app was loaded.
+On [universaleverything.io](http://universaleverything.io) this is the universal profile that has the mini-app in its grid,
+while `account[0]` will be the visitor that connected to your mini-app.
+
+```ts
+// Event for context accounts change
+provider.on('contextAccountsChanged', (contextAccountsArray: `0x${string}`[]) => {
+  // Do something with the context contextAccountsArray[0]
+})
+
+// Returns a list of context accounts, thet the parent app wants to provide
+provider.contextAccounts
+//> ['0x1234...']
+```
+
+### Examples to monitor "accountsChanged" and "chainChained"
+
 You should use some kind of watch/useEffect or other reactive function to watch the
-.on('accountsChanged') and .on('chainChanged') events. You can initially call eth_accounts and eth_chainId to initialize accounts and chainId.
+`accountsChanged`, `contextAccountsChanged` and `chainChanged'` events. You can initially call `eth_accounts`, `up_contextAccounts` (or provider.contextAccounts) and `eth_chainId` to initialize accounts and chainId.
 
 ### Example React code to monitor accountsChanged, contextAccountsChanged and chainChained
 
@@ -213,9 +257,9 @@ watch(
 )
 ```
 
-## Page side of the provider
+## Parent page side of the up-provider
 
-Server side (i.e. parent page of the iframe) setup
+The parent page side of the up-provider, is used in pages that host mini-apps and can pass up connections from iframes to a parent provider like `window.ethereum` (referred to as orignalProvider below)
 
 ```ts
 import { UPClientChannel, createUPProviderConnector } from '@lukso/up-provider'
@@ -262,10 +306,10 @@ channel.contextAccounts = addressArray
 channel.setupChannel(enable, [profileAddress], [contextAddress], chainId)
 ```
 
-## Flow diagrams
-
-[Diagrams](./docs/diagrams.md)
-
 ## API Docs
 
 [API Docs](https://lukso-network.github.io/tools-up-provider)
+
+## Flow diagrams
+
+[Diagrams](./docs/diagrams.md)