diff --git a/docs/base-app/guides/search-and-discovery.mdx b/docs/base-app/guides/search-and-discovery.mdx
new file mode 100644
index 000000000..5e5883012
--- /dev/null
+++ b/docs/base-app/guides/search-and-discovery.mdx
@@ -0,0 +1,175 @@
+---
+title: 'Mini App Search and Discovery'
+description: 'Learn how users discover and access Mini Apps in the Base ecosystem, including discovery surfaces, ranking systems, and optimization strategies for maximum visibility.'
+---
+
+> **What you’ll learn**
+> By the end of this guide, you’ll be able to:
+> - Structure your Mini App’s metadata to create rich, visually compelling user experiences.
+> - Get your Mini App indexed in Base App search and understand how indexing works.
+> - Design compelling embeds that drive clicks and engagement from social feeds.
+> - Choose the right categories and implement strategies to rank higher in “Trending Today.”
+> - Apply best practices to increase discoverability across all Base App surfaces.
+
+
+## Metadata
+
+### Manifest
+Your Mini App's [metadata](https://miniapps.farcaster.xyz/docs/specification) is defined in your manifest file located at `/.well-known/farcaster.json`. This JSON file contains all the essential information that Base App needs to display and categorize your Mini App.
+
+ Mini Apps require a complete manifest. You can read more [here](base-app/introduction/mini-apps#example-manifest)
+
+### How Metadata Works
+Each specification element in your manifest serves a specific purpose in Base's interface and directly translates into compelling visual experiences that drive user engagement.
+
+
+
+
+
+### Why It's Important
+Your metadata determines how your Mini App appears across all Base App surfaces:
+
+- **App icon (1024x1024px)**: Becomes the primary touchpoint users interact with across all surfaces
+- **Embed image (3:2 aspect ratio)**: Creates the visual hook that stops users scrolling in social feeds
+- **Tagline (50 characters max)**: Provides the instant value proposition that converts browsers into users
+- **Categories**: Determines where your app appears in Base App's browsing sections
+
+You can find the Figma file for visual guide [here](https://www.figma.com/design/4wx6s24NB0KLgprQAyMT8R/TBA-Mini-App-Specs?node-id=0-1&t=vs3713Z2RarbGRYi-1)
+
+## Design
+
+### Embeds
+When a user pastes your Mini App's link into a feed, the Base App automatically fetches your page's Open Graph metadata before the post is published. This metadata is used to render a rich embed—complete with your image, title, and call-to-action—that appears instantly in the composer and in followers' feeds. Well-designed embeds make your app stand out in fast-scrolling social contexts and can turn casual impressions into active launches.
+
+
+
+
+
+
+
+
+## Search
+
+### How Search Works
+Users discover Mini Apps through direct search queries in Base App.
+
+
+
+
+
+Your Mini App will only appear in search results after it has been indexed. To ensure indexing, share your Mini App at least once in Base App. Indexing typically takes ~10 (approx) minutes after the first share.
+
+### Managing Search Indexing
+
+**Development Environment:**
+Add `"noindex": true` to your manifest to prevent development versions from appearing in search results:
+
+```json
+{
+ "frame": {
+ "noindex": true,
+ "name": "Your App (Dev)",
+ // ... other fields
+ }
+}
+```
+
+**Removing from Search:**
+To remove your Mini App from search results:
+
+- **Invalidate manifest:** Update your manifest to make it invalid (removes from all discovery).
+
+
+If your Mini App does not show in search please follow the debugging guide [here](/base-app/build-with-minikit/debugging#1-app-discovery--indexing-issues)
+
+
+## Discovery
+
+### Trending
+The "Trending Today" section showcases the most popular Mini Apps being actively used and shared.
+
+
+
+
+
+**What determines trending status:**
+- Social sharing frequency
+- Current user engagement metrics
+
+### Saved
+Multiple surfaces help users discover Mini Apps through social interactions:
+
+**Saved Apps** - Personal launcher and quick access hub
+
+
+
+
+This surface functions like the iPhone homescreen for onchain applications. Users see their saved apps and Mini Apps in a personalized view.
+
+**What appears here:**
+- User's saved Mini Apps
+- Recently used applications
+
+**How users access your Mini App:**
+- Click on your Mini App icon after they've saved it
+- Access through recent usage if they've interacted with it recently
+
+
+You can prompt users to save your Mini App using the [useAddFrame hook](/base-app/build-with-minikit/overview#useaddframe). Consider waiting until users experience value - after completing their first action or reaching a milestone - for better conversion rates.
+
+
+**App Categories** - Browsable directory organized by interest
+
+
+
+
+
+Choose your primaryCategory carefully as it determines where your app appears in Base App's category browsing. Available categories are: games, social, finance, utility, productivity, developer-tools, and art-creativity
+
+
+
+
+
+ The Base app uses aggregated data (7-day rolling window) to generate dynamic category rankings and identify trending applications.
+
+
+### Sharing
+
+**Technical implementation:**
+```html
+
+```
+
+**Specs**
+**Best practices for embeds:**
+- Add `fc:frame` meta tags to make pages shareable as embeds
+- Optimize embed images for 3:2 aspect ratio
+- Include compelling call-to-action text in embed buttons
+- Use dynamic embed generation for personalized content
+
+
+If your Mini App does not show as an embed please follow the debugging guide [here](/base-app/build-with-minikit/debugging#3-embed-rendering-issues)
+
+
+**Build for Discovery:**
+
+- [ ] **Implement proper manifest files:** Ensure your `/.well-known/farcaster.json` includes all required metadata including proper categorization. [Example here](base-app/introduction/mini-apps#example-manifest)
+
+- [ ] **Choose relevant categories:** Select the most appropriate primary category in your manifest to appear in the right discovery sections
+
+- [ ] **Create shareable moments:** Build features that naturally encourage users to share their achievements, creations, or experiences. Follow our [Thinking Social Guide](/base-app/guides/thinking-social)
+
+- [ ] **Design compelling embeds:** Create eye-catching embed images and clear value propositions that encourage clicks from social feeds
+
+- [ ] **Encourage saves:** Implement prompts for users to save your Mini App to their personal launcher for easy return access
+
+## Next Steps
+
+Continue building your Mini App with these resources:
+
+- [MiniKit Documentation](/base-app/build-with-minikit/overview): Complete MiniKit integration guide
+- [Thinking Social](/base-app/guides/thinking-social): Social mechanics and sharing best practices
+
+
+
+By understanding and optimizing for these discovery mechanisms, you'll increase your Mini App's visibility and user engagement in the Base ecosystem. Focus particularly on social sharing mechanics and proper technical implementation to maximize your app's discoverability.
diff --git a/docs/docs.json b/docs/docs.json
index 5ab1c5852..09ae2a2f6 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -388,6 +388,7 @@
{
"group": "Guides",
"pages": [
+ "base-app/guides/search-and-discovery",
"base-app/guides/thinking-social",
"base-app/guides/chat-agents"
]
diff --git a/docs/images/minikit/categories.jpg b/docs/images/minikit/categories.jpg
new file mode 100644
index 000000000..deaafa2ae
Binary files /dev/null and b/docs/images/minikit/categories.jpg differ
diff --git a/docs/images/minikit/category_list.jpg b/docs/images/minikit/category_list.jpg
new file mode 100644
index 000000000..c91646d33
Binary files /dev/null and b/docs/images/minikit/category_list.jpg differ
diff --git a/docs/images/minikit/feed_mini.jpg b/docs/images/minikit/feed_mini.jpg
new file mode 100644
index 000000000..b81c8ba31
Binary files /dev/null and b/docs/images/minikit/feed_mini.jpg differ
diff --git a/docs/images/minikit/my-apps.jpg b/docs/images/minikit/my-apps.jpg
new file mode 100644
index 000000000..7090bdda5
Binary files /dev/null and b/docs/images/minikit/my-apps.jpg differ
diff --git a/docs/images/minikit/ranking.jpeg b/docs/images/minikit/ranking.jpeg
new file mode 100644
index 000000000..40337c6e7
Binary files /dev/null and b/docs/images/minikit/ranking.jpeg differ
diff --git a/docs/images/minikit/search.jpg b/docs/images/minikit/search.jpg
new file mode 100644
index 000000000..6fb9d440e
Binary files /dev/null and b/docs/images/minikit/search.jpg differ
diff --git a/docs/images/minikit/trending_today.jpg b/docs/images/minikit/trending_today.jpg
new file mode 100644
index 000000000..54015db1f
Binary files /dev/null and b/docs/images/minikit/trending_today.jpg differ
diff --git a/docs/instructions.md b/docs/instructions.md
new file mode 100644
index 000000000..3605cf772
--- /dev/null
+++ b/docs/instructions.md
@@ -0,0 +1,30 @@
+
+### Language and style requirements
+
+- Use clear, direct language appropriate for technical audiences
+- Write in second person ("you") for instructions and procedures
+- Use active voice over passive voice
+- Employ present tense for current states, future tense for outcomes
+- Avoid jargon unless necessary and define terms when first used
+- Maintain consistent terminology throughout all documentation
+- Keep sentences concise while providing necessary context
+- Use parallel structure in lists, headings, and procedures
+
+### Content organization standards
+
+- Lead with the most important information (inverted pyramid structure)
+- Use progressive disclosure: basic concepts before advanced ones
+- Break complex procedures into numbered steps
+- Include prerequisites and context before instructions
+- Provide expected outcomes for each major step
+- Use descriptive, keyword-rich headings for navigation and SEO
+- Group related information logically with clear section breaks
+
+### User-centered approach
+
+- Focus on user goals and outcomes rather than system features
+- Anticipate common questions and address them proactively
+- Include troubleshooting for likely failure points
+- Write for scannability with clear headings, lists, and white space
+- Include verification steps to confirm success
+