Reorganize docs with goal-based navigation for LLM-friendly routing

app/en/_meta.tsx

@@ -2,9 +2,15 @@ import {
   Book,
   BookOpen,
   GraduationCap,
+  HelpCircle,
   Home,
+  KeyRound,
+  Monitor,
   Pencil,
+  Puzzle,
   Ruler,
+  Shield,
+  Wrench,
 } from "lucide-react";
 import type { MetaRecord } from "nextra";
 
@@ -41,9 +47,23 @@ export const meta: MetaRecord = {
   "get-started": {
     title: <TitleWithIcon icon={BookOpen}>Get Started</TitleWithIcon>,
   },
-  resources: {
-    title: <TitleWithIcon icon={Pencil}>Resources</TitleWithIcon>,
+  // Goal-based navigation: USE TOOLS
+  "use-tools": {
+    title: <TitleWithIcon icon={Monitor}>Use Arcade Tools</TitleWithIcon>,
+  },
+  // Goal-based navigation: BUILD TOOLS
+  "build-tools": {
+    title: <TitleWithIcon icon={Wrench}>Build Custom Tools</TitleWithIcon>,
+  },
+  // Tool Catalog (formerly under Resources)
+  "tool-catalog": {
+    title: <TitleWithIcon icon={Puzzle}>Tool Catalog</TitleWithIcon>,
+  },
+  // Auth Providers (separated from References)
+  "auth-providers": {
+    title: <TitleWithIcon icon={KeyRound}>Auth Providers</TitleWithIcon>,
   },
+  // Keep existing sections
   guides: {
     title: <TitleWithIcon icon={Ruler}>Guides</TitleWithIcon>,
   },
@@ -53,6 +73,18 @@ export const meta: MetaRecord = {
   references: {
     title: <TitleWithIcon icon={GraduationCap}>References</TitleWithIcon>,
   },
+  // Legacy Resources (integrations will redirect to tool-catalog)
+  resources: {
+    title: <TitleWithIcon icon={Pencil}>Resources</TitleWithIcon>,
+  },
+  // Security (elevated from guides)
+  security: {
+    title: <TitleWithIcon icon={Shield}>Security</TitleWithIcon>,
+  },
+  // Help section
+  help: {
+    title: <TitleWithIcon icon={HelpCircle}>Help</TitleWithIcon>,
+  },
 };
 
 export default meta;

app/en/auth-providers/_meta.tsx

@@ -0,0 +1,8 @@
+import type { MetaRecord } from "nextra";
+
+export const meta: MetaRecord = {
+  // Individual providers are referenced via links to /references/auth-providers
+  // This is a top-level landing that clarifies the difference from integrations
+};
+
+export default meta;

app/en/auth-providers/page.mdx

@@ -0,0 +1,72 @@
+---
+title: "Auth Providers"
+description: "Configure OAuth providers for Arcade authentication"
+---
+
+import { Callout } from "nextra/components";
+
+# Auth Providers
+
+<Callout type="warning">
+**This section is for configuring OAuth connections, NOT for using pre-built tools.**
+
+- **Looking for ready-to-use tools?** → Go to [Tool Catalog](/tool-catalog)
+- **Want to use Gmail, Slack, GitHub tools?** → Go to [Tool Catalog](/tool-catalog)
+- **Need to configure custom OAuth?** → You're in the right place!
+</Callout>
+
+## What are Auth Providers?
+
+Auth Providers are OAuth configurations that enable Arcade to authenticate with external services. They define:
+
+- OAuth client credentials (client ID, secret)
+- Authorization and token URLs
+- Required scopes and permissions
+
+## When Do You Need This Section?
+
+You need to configure an auth provider when:
+
+1. **You're building custom tools** that require OAuth authentication
+2. **You're self-hosting Arcade** and need to set up your own OAuth apps
+3. **You need custom scopes** beyond what's available in pre-built tools
+4. **The service you need** doesn't have a pre-built integration
+
+<Callout type="info">
+**Most users don't need this section.** If you're using Arcade Cloud with pre-built integrations, OAuth is already configured for you.
+</Callout>
+
+## Supported Providers
+
+Arcade supports OAuth for 30+ services. See the full list in the [Auth Provider Reference](/references/auth-providers).
+
+### Popular Providers
+
+| Provider | Documentation |
+|----------|---------------|
+| Google | [Configure Google OAuth](/references/auth-providers/google) |
+| Microsoft | [Configure Microsoft OAuth](/references/auth-providers/microsoft) |
+| GitHub | [Configure GitHub OAuth](/references/auth-providers/github) |
+| Slack | [Configure Slack OAuth](/references/auth-providers/slack) |
+| Salesforce | [Configure Salesforce OAuth](/references/auth-providers/salesforce) |
+
+[See all 30+ providers →](/references/auth-providers)
+
+## Adding a Custom OAuth Provider
+
+If the service you need isn't in our list, you can add a custom OAuth 2.0 provider.
+
+[Add a custom OAuth provider →](/references/auth-providers/oauth2)
+
+## Common Confusion: Auth Providers vs Integrations
+
+| Auth Providers | Integrations (Tool Catalog) |
+|----------------|---------------------------|
+| OAuth configuration | Ready-to-use tools |
+| For custom tools | For using existing tools |
+| Technical setup | Just connect and use |
+| "How to authenticate" | "What actions can I take" |
+
+**Example:**
+- "I want to send emails via Gmail" → [Gmail Integration](/tool-catalog/productivity/gmail) (Tool Catalog)
+- "I want to configure Google OAuth for my custom tool" → [Google Auth Provider](/references/auth-providers/google) (This section)

app/en/build-tools/_meta.tsx

@@ -0,0 +1,21 @@
+import type { MetaRecord } from "nextra";
+
+export const meta: MetaRecord = {
+  quickstart: {
+    title: "Quick Start: Your First Tool",
+  },
+  "mcp-server-basics": {
+    title: "MCP Server Basics",
+  },
+  "add-authentication": {
+    title: "Add Authentication",
+  },
+  "test-evaluate": {
+    title: "Test & Evaluate",
+  },
+  deploy: {
+    title: "Deploy Your Tools",
+  },
+};
+
+export default meta;

app/en/build-tools/add-authentication/page.mdx

@@ -0,0 +1,28 @@
+---
+title: "Add Authentication to Tools"
+description: "Make your custom tools work with user credentials and OAuth"
+---
+
+import { Callout } from "nextra/components";
+
+# Add Authentication to Tools
+
+<Callout type="info">
+**Coming soon.** This page will cover adding authentication to your custom tools.
+</Callout>
+
+## What You'll Learn
+
+- Server-level vs Tool-level authentication
+- Using existing OAuth providers (Google, GitHub, Slack, etc.)
+- Adding custom OAuth providers
+- Working with API keys and secrets
+
+## In the Meantime
+
+Check out these existing guides:
+
+- [Create a Tool with Auth](/guides/create-tools/tool-basics/create-tool-auth)
+- [Create a Tool with Secrets](/guides/create-tools/tool-basics/create-tool-secrets)
+- [Server vs Tool Level Auth](/learn/server-level-vs-tool-level-auth)
+- [Auth Providers Reference](/references/auth-providers)

app/en/build-tools/deploy/page.mdx

@@ -0,0 +1,29 @@
+---
+title: "Deploy Your Tools"
+description: "Get your custom tools running in production"
+---
+
+import { Callout } from "nextra/components";
+
+# Deploy Your Tools
+
+<Callout type="info">
+**Coming soon.** This page will cover deployment options for your tools.
+</Callout>
+
+## Deployment Options
+
+| Option | Best For | Complexity |
+|--------|----------|------------|
+| Arcade Cloud | Most users | Low |
+| Arcade Deploy | Custom domains | Medium |
+| Self-hosted | Enterprise/On-prem | High |
+
+## In the Meantime
+
+Check out these existing guides:
+
+- [Deployment Overview](/guides/deployment-hosting)
+- [Arcade Cloud](/guides/deployment-hosting/arcade-cloud)
+- [Configure Engine](/guides/deployment-hosting/configure-engine)
+- [On-premise Deployment](/guides/deployment-hosting/on-prem)

app/en/build-tools/mcp-server-basics/page.mdx

@@ -0,0 +1,27 @@
+---
+title: "MCP Server Basics"
+description: "Learn how MCP servers work and how to structure your tools"
+---
+
+import { Callout } from "nextra/components";
+
+# MCP Server Basics
+
+<Callout type="info">
+**Coming soon.** This page will cover the fundamentals of MCP servers.
+</Callout>
+
+## What You'll Learn
+
+- What is an MCP server and how does it work?
+- How Arcade extends MCP with authentication and hosting
+- Local vs Cloud vs Self-hosted deployment options
+- Best practices for structuring your tools
+
+## In the Meantime
+
+Check out these existing guides:
+
+- [Build an MCP Server](/guides/create-tools/tool-basics/build-mcp-server)
+- [Compare MCP Server Types](/guides/create-tools/tool-basics/compare-server-types)
+- [Organize Your Tools](/guides/create-tools/tool-basics/organize-mcp-tools)

app/en/build-tools/page.mdx

@@ -0,0 +1,92 @@
+---
+title: "Build Custom Tools"
+description: "Create your own MCP servers and custom tools with Arcade"
+---
+
+import { Callout } from "nextra/components";
+
+# Build Custom Tools
+
+Need tools that don't exist in the catalog? Build your own MCP servers with custom logic and authentication.
+
+<Callout type="info">
+**Looking for pre-built tools?** Check the [Tool Catalog](/tool-catalog) first - we have 100+ integrations ready to use.
+</Callout>
+
+## When to Build Custom Tools
+
+- You need to integrate with an internal API
+- You want custom business logic in your tools
+- The service you need isn't in the tool catalog yet
+- You want to combine multiple operations into a single tool
+
+## Getting Started
+
+### 1. Quick Start (5 minutes)
+
+Build your first tool to understand the basics.
+
+[Start the quick tutorial →](/build-tools/quickstart)
+
+### 2. MCP Server Basics
+
+Learn how MCP servers work and how to structure your tools.
+
+- [What is an MCP Server?](/guides/create-tools/tool-basics/compare-mcp-server-types)
+- [Build an MCP Server](/guides/create-tools/tool-basics/build-mcp-server)
+- [Organize your tools](/guides/create-tools/tool-basics/organize-tools)
+
+### 3. Add Authentication
+
+Make your tools work with user credentials.
+
+- [Create a tool with auth](/guides/create-tools/tool-basics/create-tool-with-auth)
+- [Create a tool with secrets](/guides/create-tools/tool-basics/create-tool-with-secrets)
+- [Server-level vs Tool-level auth](/learn/server-level-vs-tool-level-auth)
+
+### 4. Test & Evaluate
+
+Ensure your tools work correctly before deploying.
+
+- [Why evaluate tools?](/guides/create-tools/evaluate-tools/why-evaluate)
+- [Create an evaluation suite](/guides/create-tools/evaluate-tools/create-evaluation-suite)
+- [Run evaluations](/guides/create-tools/evaluate-tools/run-evaluations)
+
+### 5. Deploy
+
+Get your tools running in production.
+
+- [Deploy to Arcade Cloud](/guides/deployment-hosting/arcade-cloud) (easiest)
+- [Self-host with Arcade Engine](/guides/deployment-hosting/configure-engine)
+- [On-premise options](/guides/deployment-hosting/on-prem)
+
+## Example: Simple Custom Tool
+
+```python
+from arcade.sdk import tool
+
+@tool
+def calculate_shipping(
+    weight_kg: float,
+    destination_country: str
+) -> dict:
+    """Calculate shipping cost based on weight and destination."""
+
+    # Your custom business logic here
+    base_rate = 5.00
+    per_kg_rate = 2.50
+    international_surcharge = 10.00 if destination_country != "US" else 0
+
+    total = base_rate + (weight_kg * per_kg_rate) + international_surcharge
+
+    return {
+        "cost_usd": total,
+        "estimated_days": 5 if destination_country == "US" else 14
+    }
+```
+
+## Next Steps
+
+1. [Start the quick tutorial](/build-tools/quickstart)
+2. [Explore the MCP reference docs](/references/mcp)
+3. [See example tools](https://github.com/ArcadeAI/arcade-ai/tree/main/examples)