Update Onboarding doc and Links doc

Author: ericbrown99

docs/mini-apps/features/links.mdx

@@ -1,11 +1,158 @@
 ---
 title: Links
-description: Handle closing the frame and opening external URLs safely
+description: Handle external navigation and URL interactions safely across clients
 ---
 
-Sdk options for external links 
+When building Mini Apps, proper link handling is crucial for providing a consistent user experience across different clients. This guide outlines best practices for external navigation and URL interactions.
 
+## Core Principles
 
-Deep links coming soon 
+### Use SDK Actions for Cross-Client Compatibility
 
+**Always use official SDK functions instead of static URLs.** Static URLs can break cross-client compatibility and may leave users unable to complete actions in your Mini App.
+
+<Warning>
+Avoid using direct HTML links (`<a href="">`, `<Link href="">`) or static URLs in your Mini App. These approaches don't work consistently across different clients and can create poor user experiences.
+</Warning>
+
+## External Navigation
+
+### Opening External URLs
+
+Use `sdk.actions.openUrl()` to safely open external websites in the client's in-app browser:
+
+```javascript
+import { sdk } from '@farcaster/frame-sdk';
+
+// ✅ Correct: Use SDK action
+const openExternalSite = () => {
+  sdk.actions.openUrl('https://example.com');
+};
+
+// ❌ Incorrect: Direct HTML link
+// <a href="https://example.com">Visit Site</a>
+```
+
+### Composing Casts
+
+Use `sdk.actions.composeCast()` instead of composer intent URLs:
+
+```javascript
+import { sdk } from '@farcaster/frame-sdk';
+
+// ✅ Correct: Use SDK action
+const shareContent = () => {
+  sdk.actions.composeCast({
+    text: 'Check out this Mini App!',
+    embeds: ['https://yourminiapp.com']
+  });
+};
+
+// ❌ Incorrect: Composer intent URLs
+// window.open('https://farcaster.com/~/compose?text=...')
+```
+
+## Best Practices
+
+### 1. Prioritize SDK Actions
+
+Before implementing any navigation or linking functionality:
+
+1. Check if an official SDK action exists for your use case
+2. Use the SDK action instead of crafting custom URLs
+3. Test across multiple clients to ensure compatibility
+
+### 2. Handle Unsupported Features Gracefully
+
+When using features that may not be supported in all clients:
+
+```javascript
+import { sdk } from '@farcaster/frame-sdk';
+
+const handleExternalLink = (url) => {
+  try {
+    sdk.actions.openUrl(url);
+  } catch (error) {
+    // Fallback behavior for unsupported clients
+    console.log('External navigation not supported');
+  }
+};
+```
+
+### 3. Avoid Client-Specific URLs
+
+Don't hardcode URLs specific to particular clients (like Warpcast URLs). Instead, use SDK actions that work across all supported clients.
+
+## Common Patterns
+
+### Navigation Buttons
+
+```javascript
+import { sdk } from '@farcaster/frame-sdk';
+
+const NavigationComponent = () => {
+  const handleExternalLink = () => {
+    sdk.actions.openUrl('https://docs.example.com');
+  };
+
+  const handleShare = () => {
+    sdk.actions.composeCast({
+      text: 'Just used this amazing Mini App!',
+      embeds: [window.location.href]
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={handleExternalLink}>
+        View Documentation
+      </button>
+      <button onClick={handleShare}>
+        Share This App
+      </button>
+    </div>
+  );
+};
+```
+
+### Conditional Navigation
+
+```javascript
+import { sdk } from '@farcaster/frame-sdk';
+
+const ConditionalNavigation = () => {
+  const context = sdk.context;
+  
+  const handleNavigation = () => {
+    // Adapt behavior based on client capabilities
+    if (context.client.clientFid) {
+      sdk.actions.openUrl('https://app-specific-url.com');
+    } else {
+      // Fallback for other clients
+      window.open('https://fallback-url.com', '_blank');
+    }
+  };
+
+  return (
+    <button onClick={handleNavigation}>
+      Open External Resource
+    </button>
+  );
+};
+```
+
+## Migration Guide
+
+If your Mini App currently uses static URLs or direct links, update them using these patterns:
+
+| Current Implementation | Recommended SDK Action |
+|----------------------|----------------------|
+| `<a href="https://external.com">` | `sdk.actions.openUrl('https://external.com')` |
+| `window.open('https://farcaster.com/~/compose?text=...')` | `sdk.actions.composeCast({ text: '...', embeds: [...] })` |
+| Farcaster-specific deeplinks | Use appropriate SDK action |
+| Direct profile links | Use SDK actions for profile navigation when available |
+
+## Future Considerations
+
+While deeplinks are not currently supported, they are on the roadmap. When they become available, this documentation will be updated with specific implementation guidance. In the meantime, continue using SDK actions for the most reliable cross-client experience.
 

docs/mini-apps/growth/optimize-onboarding.mdx

@@ -5,74 +5,93 @@ description: Reduce friction with wallet‑optional flows and clear value moment
 
 Optimize your onboarding flow to increase user engagement and retention. This guide outlines the best practices that will keep your users in-app and engaged.
 
-### Goals
+### Overview
 
-- Make first interaction instant and non-blocking
-- Authenticate only when a backend requires it; defer prompts until needed
+Deliver value instantly and avoid blocking actions.
+
+- Make the first interaction instant and non-blocking
+- Authenticate only when required for security purposes and defer prompts until necessary
 - Prefer the built-in Base Account; only offer connect/switch for alternate wallets, never gating
 - Use progressive disclosure tied to intent (buy, post, personalize)
-- Keep users in-app with SDK actions; avoid fragile deeplinks
+- Keep users in-app with [SDK actions for links](/mini-apps/features/links); avoid fragile static urls
 
 ### Recommended onboarding flow
 
 <Steps>
-<Step title="First render (no prompts)">
+<Step title="First render">
 - Show immediate value (demo content, sample state, or read-only mode)
-- Use Mini App `context` of user profile to instantly personalize
-- Primary CTA leads to a meaningful action; no upfront login/connect dialogs
+- Personalize instantly with [`context`](/mini-apps/technical-reference/minikit/provider-and-initialization) of the user's profile to instantly personalize
+- Display one clear CTA that leads to a meaningful action (e.g. "Post a message", "Buy a token", "Follow a user")
 </Step>
 
 <Step title="User initiates a protected action">
-- Backend needed: trigger Sign In with Farcaster (SIWF) / Quick Auth at this moment only
-- Onchain action: use the Base Account automatically; no explicit wallet connect flow
+- Trigger Sign In with Farcaster (SIWF) / Quick Auth only when needed per [Authentication](/mini-apps/features/Authentication)
+- For onchain actions, use the Base Account automatically. Eliminate explicit wallet connect flows
 - Alternate wallets: offer a non-blocking connect/switch option without gating exploration
 </Step>
 
 <Step title="Celebrate and amplify">
-- After success, prompt social actions via SDK (e.g., compose cast, view profile)
-- Offer next step: save progress, follow, or share
+- After success, prompt social actions via [SDK actions](/mini-apps/features/links) and [Sharing & Social Graph](/mini-apps/features/sharing-and-social-graph)
+- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/features/search-and-discovery)
 </Step>
 </Steps>
 
 ### UX patterns that work
 
+<Tip>
 - Progressive prompts: ask only when needed (buy, post, personalize)
 - Clear copy: explain why you’re asking ("Sign in to save your score")
+</Tip>
+
 - One-time deep link (Connect Account users): if SIWF requires a one-time Farcaster link to register auth address, message it as a quick, one-time setup and return the user seamlessly
 - Friendly fallbacks: if auth is skipped or fails, allow continued browsing in read-only mode
 
 ### Authentication and wallet guidance
 
-- Authentication
-  - Only when your backend needs a verified user
-  - Use SIWF/Quick Auth to issue a session (JWT) when required
-  - Do not treat Mini App context as primary auth (it can be spoofed)
-  - See: [Authentication](/mini-apps/features/Authentication)
+#### Authentication
+
+- Only when your backend needs a verified user
+- Use SIWF/Quick Auth to issue a session (JWT) when required
+
+<Warning>
+Do not treat Mini App context as primary auth (it can be spoofed)
+</Warning>
+
+Read more in [Authentication](/mini-apps/features/Authentication).
 
-- Wallet
-  - Base App provides an in-app Base Account; prefer using it automatically
-  - Do not show a connect button on first load in Base App
-  - If you support other wallets, show connect/switch as optional and non-blocking
-  - Use OnchainKit Wallet or Wagmi hooks as needed
+#### Wallets
+- Base App provides an in-app Base Account. This should be the default wallet used by your app to streamline interactions.
+- Do not show a connect button on first load
+- If you support other wallets, show connect/switch as optional and non-blocking
+- Use the OnchainKit Wallet component or Wagmi hooks as needed
 
 ### Do not use raw deeplinks
 
+<Warning>
 - Always use official SDK actions for cross-client compatibility (e.g., compose cast, view profile)
 - This prevents dead ends and ensures consistent behavior across hosts
-- See: [Links](/mini-apps/features/links)
+</Warning>
+
+Learn how to implement them with [SDK actions](/mini-apps/features/links).
 
 ### Measure activation and iterate
 
+<Info>
 - Define activation as the first successful protected action (e.g., first post, first onchain action)
 - Track funnel: first render → intent click → auth/wallet prompt → success → share/save
+</Info>
+
 - Break down Create Account vs Connect Account behavior to spot friction
 - See: Base Build Analytics (coming soon)
 
 ### Implementation checklist
 
+<Check>
 - Landing screen is usable without auth or wallet prompts
-- Use MiniKit context for analytics only; avoid using it as primary auth
 - Trigger SIWF/Quick Auth only when backend needs it
+</Check>
+
+- Use MiniKit context for analytics only; avoid using it as primary auth
 - Use Base Account seamlessly for onchain actions; no upfront connect flow
 - If supporting alternate wallets, provide optional, non-blocking connect/switch
 - Use SDK actions for social flows (compose/view) instead of deeplinks