Add redirect checker to block PRs with deleted pages missing redirects

.github/workflows/check-redirects.yml

@@ -0,0 +1,134 @@
+name: Check Redirects for Deleted Pages
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "app/**/*.md"
+      - "app/**/*.mdx"
+      - "next.config.ts"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check-redirects:
+    name: Verify Deleted Pages Have Redirects
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history needed for branch comparison
+
+      - name: Fetch base branch
+        run: git fetch origin ${{ github.base_ref }}:${{ github.base_ref }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        run: npm install -g pnpm && pnpm install
+
+      - name: Check for missing redirects
+        id: check
+        run: |
+          set -o pipefail
+          pnpm check-redirects ${{ github.base_ref }} 2>&1 | tee redirect-check-output.txt
+        continue-on-error: true
+
+      - name: Comment on PR if redirects are missing
+        if: steps.check.outcome == 'failure'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const output = fs.readFileSync('redirect-check-output.txt', 'utf8');
+
+            // Extract the missing redirects and suggestions from output
+            const body = `## 🔗 Missing Redirects Detected
+
+            This PR deletes markdown files that don't have corresponding redirects in \`next.config.ts\`.
+
+            When you delete a page, you must add a redirect to prevent broken links for users who have bookmarked the old URL.
+
+            <details>
+            <summary>📋 View Details</summary>
+
+            \`\`\`
+            ${output}
+            \`\`\`
+
+            </details>
+
+            ### How to fix
+
+            1. Open \`next.config.ts\`
+            2. Find the \`redirects()\` function
+            3. Add redirect entries for each deleted file (see suggestions above)
+            4. Push the changes
+
+            ---
+            *This check ensures we maintain URL stability for our documentation.*`;
+
+            // Check if we already commented
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('Missing Redirects Detected')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: body
+              });
+            }
+
+      - name: Remove outdated comment if check passes
+        if: steps.check.outcome == 'success'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('Missing Redirects Detected')
+            );
+
+            if (botComment) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+              });
+            }
+
+      - name: Fail if redirects are missing
+        if: steps.check.outcome == 'failure'
+        run: |
+          echo "❌ Missing redirects for deleted pages. See PR comment for details."
+          exit 1

.husky/pre-commit

@@ -29,6 +29,51 @@ if [ -n "$STAGED_DOCS" ]; then
   fi
 fi
 
+# --- Check Redirects (when markdown pages are deleted or renamed) ---
+# Detect deleted pages (D status) and renamed pages (R status - old path needs redirect)
+DELETED_PAGES=$(git diff --cached --name-status | grep -E "^D.*page\.(md|mdx)$" | cut -f2 || true)
+RENAMED_PAGES=$(git diff --cached --name-status | grep -E "^R.*page\.(md|mdx)$" | cut -f2 || true)
+
+if [ -n "$DELETED_PAGES" ] || [ -n "$RENAMED_PAGES" ]; then
+  echo "🔗 Detected deleted/renamed page(s), checking for redirects..."
+
+  # Run the TypeScript redirect checker with auto-fix (only checks staged changes)
+  # This will add redirect entries to next.config.ts if missing
+  if ! pnpm check-redirects --auto-fix --staged-only 2>&1; then
+    # Stage next.config.ts if it was modified
+    if git diff --name-only next.config.ts 2>/dev/null | grep -q "next.config.ts"; then
+      git add next.config.ts
+      echo ""
+      echo "📝 Redirect entries added to next.config.ts and staged."
+    fi
+    echo ""
+    # Check if there are placeholders vs other errors
+    if grep -q "REPLACE_WITH_NEW_PATH" next.config.ts 2>/dev/null; then
+      echo "❌ Commit blocked: Please update the placeholder destinations in next.config.ts"
+      echo "   Search for 'REPLACE_WITH_NEW_PATH' and provide actual redirect paths."
+    else
+      echo "❌ Commit blocked: Please fix the redirect issues shown above."
+    fi
+    exit 1
+  fi
+fi
+
+# --- Update Internal Links (when redirects are added) ---
+# If next.config.ts is staged, update any internal links pointing to redirected paths
+if git diff --cached --name-only | grep -q "next.config.ts"; then
+  echo "🔗 Updating internal links for new redirects..."
+
+  # Run the TypeScript update script
+  if pnpm update-links 2>/dev/null; then
+    # Stage any files that were modified
+    UPDATED_FILES=$(git diff --name-only -- 'app/**/*.mdx' 'app/**/*.tsx' 'app/**/*.md' 2>/dev/null || true)
+    if [ -n "$UPDATED_FILES" ]; then
+      echo "$UPDATED_FILES" | xargs git add
+      echo "✅ Internal links updated and staged"
+    fi
+  fi
+fi
+
 # --- Lint Staged (formatting) ---
 pnpm dlx lint-staged
 

app/_components/tool-footer.tsx

@@ -15,7 +15,7 @@ const ToolFooter: React.FC<ToolFooterProps> = ({ pipPackageName }) => (
     <div className="mt-16 grid gap-8 md:grid-cols-2">
       <QuickStartCard
         description="Arcade tools are hosted by our cloud platform and ready to be used in your agents.  Learn how."
-        href="/home/quickstart"
+        href="/get-started/quickstarts/call-tool-agent"
         icon={Cloud}
         title="Use tools hosted on Arcade Cloud"
       />
@@ -24,7 +24,7 @@ const ToolFooter: React.FC<ToolFooterProps> = ({ pipPackageName }) => (
         description={
           "Arcade tools can be self-hosted on your own infrastructure.  Learn more about self-hosting."
         }
-        href="/home/hosting-overview"
+        href="/guides/deployment-hosting"
         icon={Puzzle}
         title="Self Host Arcade tools"
       />

app/en/guides/agent-frameworks/crewai/use-arcade-tools/page.mdx → app/en/get-started/agent-frameworks/crewai/use-arcade-tools/page.mdx

@@ -8,9 +8,9 @@ import ToggleContent from "@/app/_components/toggle-content";
 
 ## Use CrewAI with Arcade
 
-In this guide, we will explore how to integrate Arcade tools into your CrewAI application. Follow the step-by-step instructions below. If a tool requires authorization, an authorization URL will appear in the console, waiting for your approval. This process ensures that only the tools you choose to authorize are executed.
+This guide explains how to integrate Arcade tools into your CrewAI application. Follow the step-by-step instructions below. If a tool requires authorization, an authorization URL will appear in the console, waiting for your approval. This process ensures that only the tools you choose to authorize execute.
 
-To tailor the tool authorization flow to meet your application's specific needs, check out the [Custom Auth Flow with CrewAI](/guides/agent-frameworks/crewai/custom-auth-flow) guide.
+To tailor the tool authorization flow to meet your application's specific needs, check out the [Custom Auth Flow with CrewAI](/get-started/agent-frameworks/crewai/custom-auth-flow) guide.
 
 <Steps>
 

app/en/guides/agent-frameworks/google-adk/overview/page.mdx → app/en/get-started/agent-frameworks/google-adk/overview/page.mdx

@@ -127,7 +127,7 @@ for tool in google_tools:
 
 Ready to start building with Arcade and OpenAI Agents? Check out these guides:
 
-- [Using Arcade tools](/guides/agent-frameworks/google-adk/use-arcade-tools) - Learn the basics of using Arcade tools with Google ADK
+- [Using Arcade tools](/get-started/agent-frameworks/google-adk/use-arcade-tools) - Learn the basics of using Arcade tools with Google ADK
 - [Creating custom tools](/guides/create-tools/tool-basics/build-mcp-server) - Build your own tools with the Arcade Tool SDK
 
-Enjoy exploring Arcade and building powerful AI-enabled applications!
+Enjoy exploring Arcade and building powerful AI-enabled applications.

app/en/guides/agent-frameworks/mastra/overview/page.mdx → app/en/get-started/agent-frameworks/mastra/overview/page.mdx

@@ -29,5 +29,5 @@ The integration works through three key mechanisms:
 
 ### Next Steps
 
-- Learn how to [use Arcade tools](/guides/agent-frameworks/mastra/use-arcade-tools) in a Mastra agent
-- Implement [user authentication handling](/guides/agent-frameworks/mastra/user-auth-interrupts) for tools in multi-user applications
+- Learn how to [use Arcade tools](/get-started/agent-frameworks/mastra/use-arcade-tools) in a Mastra agent
+- Implement [user authentication handling](/get-started/agent-frameworks/mastra/user-auth-interrupts) for tools in multi-user applications

app/en/guides/agent-frameworks/mastra/use-arcade-tools/page.mdx → app/en/get-started/agent-frameworks/mastra/use-arcade-tools/page.mdx

@@ -158,4 +158,4 @@ for await (const chunk of stream.textStream) {
 
 </Steps>
 
-<Callout type="warning" title="Initial Tool Authorization">When running your agent for the first time with tools that require user consent (like Google or Github), the agent will return an authorization reponse (e.g., `{ authorization_required: true, url: '...', message: '...' }`). Your agent's instructions should guide it to present this URL to the user. After the user visits this URL and grants permissions, the tool can be used successfully. See the [Managing user authorization](/guides/agent-frameworks/mastra/user-auth-interrupts) guide for more details on handling authentication flows.</Callout>
+<Callout type="warning" title="Initial Tool Authorization">When running your agent for the first time with tools that require user consent (like Google or Github), the agent will return an authorization reponse (for example, `{ authorization_required: true, url: '...', message: '...' }`). Your agent's instructions should guide it to present this URL to the user. After the user visits this URL and grants permissions, the tool can be used successfully. See the [Managing user authorization](/get-started/agent-frameworks/mastra/user-auth-interrupts) guide for more details on handling authentication flows.</Callout>

app/en/guides/agent-frameworks/openai-agents/overview/page.mdx → app/en/get-started/agent-frameworks/openai-agents/overview/page.mdx

@@ -177,8 +177,8 @@ For a full list of available MCP Servers, visit the [Arcade MCP Servers](/resour
 
 Ready to start building with Arcade and OpenAI Agents? Check out these guides:
 
-- [Using Arcade tools](/guides/agent-frameworks/openai-agents/use-arcade-tools) - Learn the basics of using Arcade tools with OpenAI Agents
-- [Managing user authorization](/guides/agent-frameworks/openai-agents/user-auth-interrupts) - Handle tool authorization efficiently
+- [Using Arcade tools](/get-started/agent-frameworks/openai-agents/use-arcade-tools) - Learn the basics of using Arcade tools with OpenAI Agents
+- [Managing user authorization](/get-started/agent-frameworks/openai-agents/user-auth-interrupts) - Handle tool authorization efficiently
 - [Creating custom tools](/guides/create-tools/tool-basics/build-mcp-server) - Build your own tools with the Arcade Tool SDK
 
 Enjoy exploring Arcade and building powerful AI-enabled applications!

app/en/guides/agent-frameworks/setup-arcade-with-your-llm-python/page.mdx → app/en/get-started/agent-frameworks/setup-arcade-with-your-llm-python/page.mdx

@@ -313,7 +313,7 @@ With the selection of tools above, you should be able to get the agent to effect
 
 ## Next Steps
 
-- Learn more about using Arcade with a [framework](/guides/agent-frameworks) or [MCP client](/guides/tool-calling/mcp-clients).
+- Learn more about using Arcade with a [framework](/get-started/agent-frameworks) or [MCP client](/get-started/mcp-clients).
 - Learn more about how to [build your own MCP Servers](/guides/create-tools/tool-basics/build-mcp-server).
 
 ## Example code

app/en/get-started/quickstarts/call-tool-agent/page.mdx

@@ -356,7 +356,7 @@ console.log(respose_send_email.output?.value);
 
 ## Next Steps
 
-In this simple example, we call the tool methods directly. In your real applications and agents, you'll likely be letting the LLM decide which tools to call. Learn more about using Arcade with Frameworks in the [Frameworks](/guides/agent-frameworks) section, or [how to build your own tools](/guides/create-tools/tool-basics/build-mcp-server).
+In this simple example, we call the tool methods directly. In your real applications and agents, you'll likely be letting the LLM decide which tools to call. Learn more about using Arcade with Frameworks in the [Frameworks](/get-started/agent-frameworks) section, or [how to build your own tools](/guides/create-tools/tool-basics/build-mcp-server).
 
 ## Example Code
 

app/en/get-started/quickstarts/call-tool-client/page.mdx

@@ -6,7 +6,7 @@ description: "Learn how to call a tool in your IDE/MCP Client"
 import { Steps, Tabs, Callout } from "nextra/components";
 import { SignupLink } from "@/app/_components/analytics";
 import Image from "next/image";
-import { MCPClientGrid } from "@/app/en/guides/tool-calling/mcp-clients/mcp-client-grid";
+import { MCPClientGrid } from "@/app/en/get-started/mcp-clients/mcp-client-grid";
 
 export const IMAGE_SCALE_FACTOR = 2;
 export const CREATE_MCP_GATEWAY_DARK_WIDTH = 921;
@@ -148,4 +148,7 @@ As you interact with the agent, it will call the tools from the MCP Gateway. You
 ## Next Steps
 
 - Learn more about [MCP Gateways](/guides/create-tools/mcp-gateways).
+- Learn how to use MCP Gateways with:
+  - [Cursor](/get-started/mcp-clients/cursor)
+  - [Visual Studio Code](/get-started/mcp-clients/visual-studio-code)
 - Build your own MCP servers with [arcade-mcp](/get-started/quickstarts/mcp-server-quickstart).

app/en/guides/_meta.tsx

@@ -7,9 +7,6 @@ export const meta: MetaRecord = {
   "create-tools": {
     title: "Create tools",
   },
-  "agent-frameworks": {
-    title: "Agent frameworks",
-  },
   "user-facing-agents": {
     title: "User-facing agents",
   },

app/en/guides/create-tools/mcp-gateways/page.mdx

@@ -51,6 +51,6 @@ The options available when configuring an MCP Gateway are:
 
 Any MCP client that supports the Streamable HTTP transport can use an Arcade MCP Gateway. To use an Arcade MCP Gateway, you can use the `https://api.arcade.dev/mcp/<YOUR-GATEWAY-SLUG>` URL in your MCP client. Learn how to use MCP Gateways with:
 
-- [Cursor](/guides/tool-calling/mcp-clients/cursor)
-- [Claude Desktop](/guides/tool-calling/mcp-clients/claude-desktop)
-- [Visual Studio Code](/guides/tool-calling/mcp-clients/visual-studio-code)
+- [Cursor](/get-started/mcp-clients/cursor)
+- [Claude Desktop](/get-started/mcp-clients/claude-desktop)
+- [Visual Studio Code](/get-started/mcp-clients/visual-studio-code)

app/en/guides/deployment-hosting/on-prem/page.mdx

@@ -284,9 +284,9 @@ You can now test your MCP Server by making requests using the Playground, or an
 <Tabs.Tab>
 
 1. Use an app that supports MCP clients, like AI assistants and IDEs:
-   - [Visual Studio Code](/guides/tool-calling/mcp-clients/visual-studio-code)
-   - [Claude Desktop](/guides/tool-calling/mcp-clients/claude-desktop)
-   - [Cursor](/guides/tool-calling/mcp-clients/cursor)
+   - [Visual Studio Code](/get-started/mcp-clients/visual-studio-code)
+   - [Claude Desktop](/get-started/mcp-clients/claude-desktop)
+   - [Cursor](/get-started/mcp-clients/cursor)
 1. Enable your MCP Server from the list of available MCP Servers
 1. Verify that the response is correct and you see request logs in your MCP Server
 

app/en/guides/tool-calling/_meta.tsx

@@ -7,9 +7,6 @@ export const meta: MetaRecord = {
   "call-third-party-apis": {
     title: "Call third-party APIs",
   },
-  "mcp-clients": {
-    title: "Connect to MCP clients",
-  },
   "custom-apps": {
     title: "In custom applications",
   },

app/en/home/landing-page.tsx

@@ -345,7 +345,7 @@ export function LandingPage() {
               <div className="space-y-4">
                 <QuickStartCard
                   description="Add tools to Cursor, VS Code, Claude Desktop, or any MCP client."
-                  href="/guides/tool-calling/mcp-clients"
+                  href="/get-started/mcp-clients"
                   icon={Monitor}
                   logos={[
                     {
@@ -364,7 +364,7 @@ export function LandingPage() {
                 />
                 <QuickStartCard
                   description="Integrate with LangChain, OpenAI Agents, CrewAI, Vercel AI, and more."
-                  href="/guides/agent-frameworks"
+                  href="/get-started/agent-frameworks"
                   icon={Code}
                   logos={[
                     {

app/en/references/changelog/page.mdx

@@ -544,7 +544,7 @@ Self-hosed Arcade developers cannot be grandfathered into the old (insecure) beh
 
 **Frameworks**
 
-- `[feature - 🚀]` Support for OpenAI Agent SDK in Typescript ([docs](/guides/agent-frameworks/openai-agents/overview) and [example](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/openai-agents-ts))
+- `[feature - 🚀]` Support for OpenAI Agent SDK in Typescript ([docs](/get-started/agent-frameworks/openai-agents/overview) and [example](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/openai-agents-ts))
 
 **Toolkits**
 

app/en/resources/integrations/productivity/gmail/page.mdx

@@ -272,7 +272,7 @@ Delete a draft email using the Gmail API.
 <Callout type="warning" emoji="⚠️">
   The `TrashEmail` tool is currently only available on a self-hosted instance of
   the Arcade Engine. To learn more about self-hosting, see the [self-hosting
-  documentation](http://localhost:3000/en/home/deployment/engine-configuration).
+  documentation](http://localhost:3000/en/guides/deployment-hosting/configure-engine).
 </Callout>
 
 <br />