vechain · Agilulfo1820 · May 20, 2026 · May 19, 2026 · May 19, 2026
diff --git a/connection-types.md b/connection-types.md
@@ -22,15 +22,21 @@ This connection type is often used by organizations like VeBetterDAO, Cleanify,
 * Your users will need to login into other apps through ecosystem mode
 {% endhint %}
 
-## 2) Privy Cross App
+## 2) Privy Cross App (VeChain whitelabel)
 
-When users integrate VeChain-kit using "Login with VeChain" and "Ecosystem" logins (eg: Mugshot and Greencart), this will be the default connection type. It is easily recognizable because login and wallet activities will open a secured popup window where the owner of the wallet will approve the actions.
+This is the default connection type when your app **does not** pass a `privy` prop to `VeChainKitProvider`. Social logins (Google, Apple, X, Discord, GitHub, TikTok, LINE, and the multi-provider "Continue with VeChain" picker) run through VeChain's whitelabel popup at [`connect.vechain.org`](https://connect.vechain.org). The popup handles the OAuth handshake, decodes the transaction in plain language for the user, and posts the signed result back to your dApp.
 
 <figure><img src="../.gitbook/assets/image (3) (1).png" alt=""><figcaption></figcaption></figure>
 
-{% hint style="info" %}
-With this type of connection, you can have social login in your app without actually paying Privy.
-{% endhint %}
+Why this is the default in v2.7+:
+
+* **Free social login** — no Privy account, no API keys, no billing. Drop a `{ method: 'google' }` button and it works.
+* **One identity across the ecosystem** — the user's VeChain address is the same in every kit-integrated dApp, so balances, NFTs and domains follow them.
+* **VeChain-branded** — the popup is whitelabeled (logo, palette, dark/light, 17 languages matching the kit). No Privy chrome leaks through.
+* **Smart-contract-aware transaction review** — instead of raw hex, the user sees "Send 10 B3TR to vechain.vet" or "Vote FOR on a VeBetterDAO proposal" with verified-contract chips.
+* **Auto-recovery from stale sessions** — if the connection record expires, the kit logs the user out and re-opens the login modal automatically.
+
+Use this option unless you have a specific reason to self-host Privy (see option 1).
 
 ## 3) Self-custody wallets
 

diff --git a/docs/connection-types.md b/docs/connection-types.md
@@ -20,13 +20,19 @@ This connection type is often used by organizations like VeBetterDAO, Cleanify,
 * Your users will need to login into other apps through ecosystem mode
 {% endhint %}
 
-## 2) Privy Cross App
+## 2) Privy Cross App (VeChain whitelabel)
 
-When users integrate VeChain-kit using "Login with VeChain" and "Ecosystem" logins (eg: Mugshot and Greencart), this will be the default connection type. It is easily recognizable because login and wallet activities will open a secured popup window where the owner of the wallet will approve the actions.
+This is the default connection type when your app **does not** pass a `privy` prop to `VeChainKitProvider`. Social logins (Google, Apple, X, Discord, GitHub, TikTok, LINE, and the multi-provider "Continue with VeChain" picker) run through VeChain's whitelabel popup at [`connect.vechain.org`](https://connect.vechain.org). The popup handles the OAuth handshake, decodes the transaction in plain language for the user, and posts the signed result back to your dApp.
 
-{% hint style="info" %}
-With this type of connection, you can have social login in your app without actually paying Privy.
-{% endhint %}
+Why this is the default in v2.7+:
+
+* **Free social login** — no Privy account, no API keys, no billing. Drop a `{ method: 'google' }` button and it works.
+* **One identity across the ecosystem** — the user's VeChain address is the same in every kit-integrated dApp, so balances, NFTs and domains follow them.
+* **VeChain-branded** — the popup is whitelabeled (logo, palette, dark/light, 17 languages matching the kit). No Privy chrome leaks through.
+* **Smart-contract-aware transaction review** — instead of raw hex, the user sees "Send 10 B3TR to vechain.vet" or "Vote FOR on a VeBetterDAO proposal" with verified-contract chips.
+* **Auto-recovery from stale sessions** — if the connection record expires, the kit logs the user out and re-opens the login modal automatically.
+
+Use this option unless you have a specific reason to self-host Privy (see option 1).
 
 ## 3) Self-custody wallets
 

diff --git a/docs/quickstart/login-customization.md b/docs/quickstart/login-customization.md
@@ -6,7 +6,7 @@ This guide covers the connect-modal authentication surface in VeChain Kit. From
 
 - **Custom in-house connection flow** for VeWorld and Sync2. Clicking a wallet button drives `@vechain/dapp-kit` programmatically (`setSource()` + `connect()`) and renders the kit's own "Waiting for signature…" view. WalletConnect's QR modal is preserved because that modal _is_ the QR.
 - **Granular `loginMethods`**: `veworld`, `sync2`, `wallet-connect`, `apple` are now first-class entries you can pin individually. The legacy `dappkit` value still works.
-- **Variation A layout**: VeWorld primary filled (recommended), Google + Apple as outline secondary, "More options ⌄" link footer that opens an in-modal sub-view with overflow wallets / socials / ecosystem apps.
+- **Variation A layout**: one recommended primary CTA (filled inverted + "recommended" dot) — usually VeWorld in the default config, but the dev controls which method gets the emphasis via `isPrimary`; the rest render as outline secondary. "More options ⌄" link footer opens an in-modal sub-view with overflow wallets / socials / ecosystem apps.
 - **Themeable accent**: spinner, focus rings and the "Waiting for signature…" headline read from `theme.accent`.
 
 ### Overview
@@ -88,7 +88,7 @@ await initOAuth({ provider: 'google' }); // 'google' | 'apple' | 'github' | 'dis
 
 ### Configuring the grid: `loginMethods`
 
-The order and shape of the connect-modal grid is controlled by `loginMethods` on `<VeChainKitProvider>`. Each entry has a `method` and an optional `gridColumn` (1–4 — buttons span that many of the 4 columns).
+The order and shape of the connect-modal grid is controlled by `loginMethods` on `<VeChainKitProvider>`. Each entry has a `method`, an optional `gridColumn` (1–4 — buttons span that many of the 4 columns), and an optional `isPrimary` flag that controls which button gets the recommended-CTA treatment.
 
 ```tsx
 <VeChainKitProvider
@@ -103,14 +103,39 @@ The order and shape of the connect-modal grid is controlled by `loginMethods` on
     walletConnectOptions: { /* ... */ },
   }}
   loginMethods={[
-    { method: 'veworld', gridColumn: 4 },   // primary CTA — filled, "recommended" dot
-    { method: 'google',  gridColumn: 4 },   // outline secondary
-    { method: 'apple',   gridColumn: 4 },   // outline secondary
-    { method: 'more',    gridColumn: 4 },   // opens an in-modal sub-view
+    { method: 'veworld', gridColumn: 4, isPrimary: true },  // recommended CTA — filled, "recommended" dot
+    { method: 'google',  gridColumn: 4 },                   // outline secondary
+    { method: 'apple',   gridColumn: 4 },                   // outline secondary
+    { method: 'more',    gridColumn: 4 },                   // opens an in-modal sub-view
   ]}
 >
 ```
 
+#### Recommended primary CTA — `isPrimary`
+
+One method per grid renders as the recommended CTA: filled inverted surface (dark on light mode, white on dark mode) with a small green dot. The rest render as outline secondary. Two ways the kit picks which:
+
+1. **Explicit** — any entry with `isPrimary: true` (excluding `more`, which is a footer link). If multiple entries set `isPrimary`, the first one wins.
+2. **Implicit fallback** — when no entry sets `isPrimary`, the kit highlights the first visible method in the array. So a minimal config like `[{ method: 'google' }, { method: 'apple' }]` still gets Google as the recommended CTA without thinking about emphasis.
+
+Currently supported as primary: `veworld`, `google`, `apple`, `github`. Other methods can sit on the main grid but won't switch to the filled treatment when first / `isPrimary: true` — they keep their outline look. (Adding more is a one-prop change per button; open an issue if you need it.)
+
+```tsx
+// Default: Google is primary because it's first.
+loginMethods={[
+  { method: 'google',  gridColumn: 4 },
+  { method: 'apple',   gridColumn: 4 },
+  { method: 'more',    gridColumn: 4 },
+]}
+
+// Explicit: Apple is primary, Google is outline.
+loginMethods={[
+  { method: 'google',  gridColumn: 4 },
+  { method: 'apple',   gridColumn: 4, isPrimary: true },
+  { method: 'more',    gridColumn: 4 },
+]}
+```
+
 #### Method values
 
 | Method            | Requires                                                                                  | Renders                                                                                  |

diff --git a/docs/quickstart/provider-configuration.md b/docs/quickstart/provider-configuration.md
@@ -75,10 +75,10 @@ export function VeChainKitProviderWrapper({ children }: { children: React.ReactN
 
       // Login Methods Configuration (variation A default)
       loginMethods={[
-        { method: "veworld", gridColumn: 4 },  // primary CTA, recommended
+        { method: "veworld", gridColumn: 4, isPrimary: true },  // recommended CTA, filled + dot
         { method: "google",  gridColumn: 4 },
         { method: "apple",   gridColumn: 4 },
-        { method: "more",    gridColumn: 4 },  // overflow sub-view (wallets / socials / ecosystem)
+        { method: "more",    gridColumn: 4 },                   // overflow sub-view (wallets / socials / ecosystem)
       ]}
 
       // Sponsor transactions
@@ -135,25 +135,30 @@ feeDelegation: {
 
 #### Login Methods
 
-Configure available authentication methods with a flexible grid layout. Each entry pins a `method` and an optional `gridColumn` (1–4) controlling how many of the 4 columns the button spans.
+Configure available authentication methods with a flexible grid layout. Each entry pins a `method`, an optional `gridColumn` (1–4) controlling how many of the 4 columns the button spans, and an optional `isPrimary` flag that promotes the button to the recommended CTA (filled inverted surface + "recommended" green dot). If no entry sets `isPrimary`, the kit falls back to highlighting the first visible method. Only one button per grid is primary; `isPrimary` on the `more` footer link is ignored. The filled treatment currently supports `veworld`, `google`, `apple`, and `github`.
 
 ```typescript
 loginMethods: [
   // --- Wallets (drives @vechain/dapp-kit programmatically; kit owns the UI) ---
-  { method: "veworld",        gridColumn: 4 },  // primary CTA — filled, recommended dot
+  { method: "veworld",        gridColumn: 4, isPrimary: true },  // recommended CTA — filled, dot
   { method: "sync2",          gridColumn: 4 },
   { method: "wallet-connect", gridColumn: 4 },  // triggers WC's own QR modal
 
   // --- VeChain native ---
   { method: "vechain",   gridColumn: 4 },       // VeChain cross-app social login
   { method: "ecosystem", gridColumn: 4 },       // x2earn ecosystem apps footer
 
-  // --- Privy social (require `privy` configuration) ---
-  { method: "google",  gridColumn: 4 },
-  { method: "apple",   gridColumn: 4 },
-  { method: "github",  gridColumn: 4 },
-  { method: "email",   gridColumn: 4 },
-  { method: "passkey", gridColumn: 4 },
+  // --- Social (routed through VeChain's whitelabel cross-app popup unless you pass `privy`) ---
+  { method: "google",  gridColumn: 4 },         // works without `privy` (cross-app intent)
+  { method: "apple",   gridColumn: 4 },         // works without `privy`
+  { method: "twitter", gridColumn: 4 },         // works without `privy`
+  { method: "discord", gridColumn: 4 },         // works without `privy`
+  { method: "github",  gridColumn: 4 },         // works without `privy`
+  { method: "tiktok",  gridColumn: 4 },         // works without `privy`
+  { method: "line",    gridColumn: 4 },         // works without `privy`
+  { method: "email",   gridColumn: 4 },         // requires your own `privy` (inline, no popup)
+  { method: "passkey", gridColumn: 4 },         // requires your own `privy`
+  { method: "sms",     gridColumn: 4 },         // requires your own `privy`
   { method: "more",    gridColumn: 4 },         // sub-view with overflow socials/wallets/ecosystem
 
   // --- Legacy ---
@@ -206,7 +211,9 @@ function MyComponent() {
 
 ### Privy Integration (Optional)
 
-To enable social login methods with your own Privy account:
+Most social logins work without your own Privy account — the kit routes Google / Apple / X / Discord / GitHub / TikTok / LINE through VeChain's whitelabel cross-app popup automatically. Pass the `privy` prop only if you need email, passkey, SMS, additional OAuth providers, or want the login flow to render entirely inside your dApp instead of in a popup window.
+
+To enable those flows with your own Privy account:
 
 ```typescript
 <VeChainKitProvider

diff --git a/docs/quickstart/setup-privy-optional.md b/docs/quickstart/setup-privy-optional.md
@@ -1,5 +1,11 @@
 # Setup Privy (optional)
 
+{% hint style="success" %}
+**You do not need a Privy account to ship social login.** By default, VeChain Kit routes Google, Apple, X, Discord, GitHub, TikTok, LINE, and the multi-provider "Continue with VeChain" button through VeChain's whitelabel cross-app popup at [`connect.vechain.org`](https://connect.vechain.org) — branded for VeChain, free, and the user keeps a single identity across every kit-integrated dApp.
+
+Self-host Privy only if you need email / passkey / SMS login, additional OAuth providers, no popup, or branding-inside-your-dApp transaction prompts. See _Pros / Cons_ at the bottom of this page.
+{% endhint %}
+
 If you have your own Privy app, you can pass an additional prop with your settings.
 
 ```javascript
@@ -57,13 +63,15 @@ If you setup your own Privy be sure to go over the recommended security settings
 {% hint style="info" %}
 **Pros of self hosting Privy:**
 
-* No UI confirmations on users transactions
-* Allow your users to backup their keys and update security settings directly in your app
-* Targetted social login methods
+* No UI confirmations on user transactions (no popup window per signature)
+* Allow your users to back up their keys and update security settings directly in your app
+* Email / passkey / SMS login (these can't run via the whitelabel popup)
+* Additional OAuth providers Privy supports but VeChain's whitelabel doesn't enable (LinkedIn, Spotify, …)
+* Your dApp's branding throughout the login modal
 
 **Cons:**
 
-* Price
-* Responsibilities to correctly secure your Privy account, since it contains access to user's wallet settings
-* Your users will need to login into other apps through ecosystem mode
+* Price (Privy pricing tiers)
+* Responsibility to correctly secure your Privy account, since it contains access to users' wallet settings
+* Users have their own wallet scoped to your dApp instead of a single VeChain-wide identity (cross-app linking still possible via ecosystem mode)
 {% endhint %}
diff --git a/quickstart/provider-configuration.md b/quickstart/provider-configuration.md
@@ -131,20 +131,30 @@ feeDelegation: {
 
 #### Login Methods
 
-Configure available authentication methods with a flexible grid layout:
+Configure available authentication methods with a flexible grid layout. Mark one entry with `isPrimary: true` to render it as the recommended CTA (filled inverted surface + green "recommended" dot). If you don't, the kit highlights the first visible method automatically. The filled treatment currently supports `veworld`, `google`, `apple`, and `github`; other methods can sit on the grid but stay outline.
 
 ```typescript
 loginMethods: [
   // Always available methods
-  { method: "vechain", gridColumn: 4 },    // VeChain social login
-  { method: "dappkit", gridColumn: 4 },    // VeChain wallets
-  { method: "ecosystem", gridColumn: 4 },  // Ecosystem apps (Mugshot, Cleanify, Greencart, etc.)
-
-  // Privy-dependent methods (require your own privy configuration)
-  { method: "email", gridColumn: 2 },      // Email login
+  { method: "veworld", gridColumn: 4, isPrimary: true },    // recommended CTA — filled, dot
+  { method: "vechain", gridColumn: 4 },                     // VeChain whitelabel cross-app picker
+  { method: "dappkit", gridColumn: 4 },                     // VeChain wallets
+  { method: "ecosystem", gridColumn: 4 },                   // Ecosystem apps (Mugshot, Cleanify, Greencart, etc.)
+
+  // OAuth methods — work WITHOUT your own Privy account (routed via the whitelabel cross-app popup)
+  { method: "google",  gridColumn: 4 },    // Google
+  { method: "apple",   gridColumn: 4 },    // Apple
+  { method: "twitter", gridColumn: 4 },    // X / Twitter
+  { method: "discord", gridColumn: 4 },    // Discord
+  { method: "github",  gridColumn: 4 },    // GitHub
+  { method: "tiktok",  gridColumn: 4 },    // TikTok
+  { method: "line",    gridColumn: 4 },    // LINE
+
+  // Privy-dependent methods (require your own privy configuration — inline, no popup)
+  { method: "email",   gridColumn: 2 },    // Email login
   { method: "passkey", gridColumn: 2 },    // Passkey authentication
-  { method: "google", gridColumn: 4 },     // Google OAuth
-  { method: "more", gridColumn: 2 },       // Additional Privy methods
+  { method: "sms",     gridColumn: 2 },    // SMS login
+  { method: "more",    gridColumn: 2 },    // Sub-view with overflow socials/wallets/ecosystem
 ]
 ```
 
@@ -186,7 +196,9 @@ function MyComponent() {
 
 ### Privy Integration (Optional)
 
-To enable social login methods with your own Privy account:
+Most social logins work without your own Privy account — the kit routes Google / Apple / X / Discord / GitHub / TikTok / LINE through VeChain's whitelabel cross-app popup automatically. Pass the `privy` prop only if you need email, passkey, SMS, additional OAuth providers, or want the login flow to render entirely inside your dApp instead of in a popup window.
+
+To enable those flows with your own Privy account:
 
 ```typescript
 <VeChainKitProvider

diff --git a/quickstart/setup-privy-optional.md b/quickstart/setup-privy-optional.md
@@ -1,5 +1,11 @@
 # Setup Privy (optional)
 
+{% hint style="success" %}
+**You do not need a Privy account to ship social login.** By default, VeChain Kit routes Google, Apple, X, Discord, GitHub, TikTok, LINE, and the multi-provider "Continue with VeChain" button through VeChain's whitelabel cross-app popup at [`connect.vechain.org`](https://connect.vechain.org) — branded for VeChain, free, and the user keeps a single identity across every kit-integrated dApp.
+
+Self-host Privy only if you need email / passkey / SMS login, additional OAuth providers, no popup, or branding-inside-your-dApp transaction prompts. See _Pros / Cons_ at the bottom of this page.
+{% endhint %}
+
 If you have your own Privy app, you can pass an additional prop with your settings.
 
 ```javascript
@@ -57,13 +63,15 @@ If you setup your own Privy be sure to go over the recommended security settings
 {% hint style="info" %}
 **Pros of self hosting Privy:**
 
-* No UI confirmations on users transactions
-* Allow your users to backup their keys and update security settings directly in your app
-* Targetted social login methods
+* No UI confirmations on user transactions (no popup window per signature)
+* Allow your users to back up their keys and update security settings directly in your app
+* Email / passkey / SMS login (these can't run via the whitelabel popup)
+* Additional OAuth providers Privy supports but VeChain's whitelabel doesn't enable (LinkedIn, Spotify, …)
+* Your dApp's branding throughout the login modal
 
 **Cons:**
 
-* Price
-* Responsibilities to correctly secure your Privy account, since it contains access to user's wallet settings
-* Your users will need to login into other apps through ecosystem mode
+* Price (Privy pricing tiers)
+* Responsibility to correctly secure your Privy account, since it contains access to users' wallet settings
+* Users have their own wallet scoped to your dApp instead of a single VeChain-wide identity (cross-app linking still possible via ecosystem mode)
 {% endhint %}