ArcadeAI · evantahler · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.cursorrules b/.cursorrules
@@ -5,7 +5,7 @@ You are writing documentation for Arcade, an AI platform for developers. Follow
 3. **Sentence case**: Use sentence case for titles and headings.
 4. **Active voice**: Make instructions direct and easy to follow.
 5. **Friendly and supportive**: Assume the reader is eager to learn, and maintain a positive, approachable tone.
-6. **Developer-focused**: Tailor language to developers. Assume basic Python knowledge but introduce Arcade concepts clearly.
+6. **Persona-aware**: Write for agent developers (Get Started, Build) or platform operators (Operate). Name the audience in the page intro. For developers, assume basic Python knowledge; for operators, focus on deploy, identity, and governance.
 7. **Encourage exploration**: Use phrases that invite experimentation, like “Let’s try…” or “You can explore…”
 8. **Always refer to the product as 'Arcade'**. Do not abbreviate or shorten the product name.
 9. **Code first**: Provide clear, copy/paste-ready code snippets, with brief, essential comments.

diff --git a/AUTHORING.md b/AUTHORING.md
@@ -12,7 +12,7 @@ These are the guidelines for writing documentation for Arcade, to help keep the
 
 - **Active voice**: Write in an active voice to make the instructions direct and easy to follow. Example: “Install Arcade” rather than “Arcade should be installed.”
 - **Friendly and supportive**: Assume the reader is unfamiliar with Arcade but is eager to learn. Keep the tone positive, friendly, and approachable.
-- **Developer-focused**: Tailor your language to a developer audience, using code-centric explanations but ensuring clarity for beginners. Assume the reader knows Python but might be unfamiliar with Arcade’s specifics.
+- **Persona-aware**: Arcade docs serve **agent developers** (Get Started, Build) and **platform operators** (Operate). Open each page by naming who it is for. For agent developers, use code-centric explanations and assume basic Python knowledge. For platform operators, emphasize deployment, identity, and governance; link out to Build when code samples belong there.
 - **Encouraging exploration**: Use phrases that invite readers to try things out and explore the capabilities of Arcade. Example: “Let’s try…” or “You can explore…”
 
 ## Examples and code

diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md
@@ -15,6 +15,22 @@ Vale handles mechanical style checks (grammar, passive voice, etc.). This guide
 
 Assume readers know programming fundamentals. Don't explain what a function is, but do explain Arcade-specific concepts.
 
+### Write for the right persona
+
+Arcade docs serve two primary personas. State which one a page is for in the opening paragraph.
+
+| Persona | Who they are | Primary sections |
+| --- | --- | --- |
+| **Agent developer** | Builds agents, calls tools, or ships custom MCP servers | Get Started, Build |
+| **Platform operator** | Deploys, secures, and governs Arcade for an organization | Operate |
+
+Shared sections (Learn, Resources, References) serve both. When a topic diverges by job, link to the other persona's path instead of mixing both workflows on one page.
+
+- **Do:** "These docs are for platform operators who deploy Arcade for a company."
+- **Don't:** Assume every reader is building an agent, or bury operator setup under developer quickstarts.
+
+Prefer **Operate** (or "platform operator") over vague labels like "Enterprise" when naming navigation or page audiences.
+
 ### Use "you" for the reader
 
 - **Do:** "You can configure the server with environment variables" or "Configure the server with environment variables"

diff --git a/app/_components/starter-tool-info.tsx b/app/_components/starter-tool-info.tsx
@@ -10,7 +10,7 @@ const StarterToolInfo: React.FC<StarterToolInfoProps> = ({ toolkitName }) => (
     <p>
       {toolkitName} is a{" "}
       <u>
-        <a href="/guides/create-tools/improve/types-of-tools#unoptimized-tools">
+        <a href="/build/create-tools/improve/types-of-tools#unoptimized-tools">
           Unoptimized MCP Server
         </a>
       </u>
@@ -21,15 +21,15 @@ const StarterToolInfo: React.FC<StarterToolInfoProps> = ({ toolkitName }) => (
     <p>
       Differently from{" "}
       <u>
-        <a href="/guides/create-tools/improve/types-of-tools#optimized-tools">
+        <a href="/build/create-tools/improve/types-of-tools#optimized-tools">
           Optimized MCP Servers
         </a>
       </u>
       , Unoptimized tools are heavily influenced by the original API design,
       which is not usually optimized for LLM usage. For this reason, we
       recommend thoroughly evaluating the tools with your Agents or chatbots
       before using it in production.{" "}
-      <a href="/guides/create-tools/improve/types-of-tools">Read more</a> about
+      <a href="/build/create-tools/improve/types-of-tools">Read more</a> about
       Optimized vs Unoptimized tools.
     </p>
   </Callout>

diff --git a/app/_components/tool-footer.tsx b/app/_components/tool-footer.tsx
@@ -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="/guides/deployment-hosting"
+        href="/operate/deploy"
         icon={Puzzle}
         title="Self Host Arcade tools"
       />

diff --git a/app/en/_meta.tsx b/app/en/_meta.tsx
@@ -5,6 +5,7 @@ import {
   Home,
   Pencil,
   Ruler,
+  ServerCog,
 } from "lucide-react";
 import type { MetaRecord } from "nextra";
 
@@ -41,12 +42,15 @@ export const meta: MetaRecord = {
   "get-started": {
     title: <TitleWithIcon icon={BookOpen}>Get Started</TitleWithIcon>,
   },
+  build: {
+    title: <TitleWithIcon icon={Ruler}>Build</TitleWithIcon>,
+  },
+  operate: {
+    title: <TitleWithIcon icon={ServerCog}>Operate</TitleWithIcon>,
+  },
   resources: {
     title: <TitleWithIcon icon={Pencil}>Resources</TitleWithIcon>,
   },
-  guides: {
-    title: <TitleWithIcon icon={Ruler}>Guides</TitleWithIcon>,
-  },
   learn: {
     title: <TitleWithIcon icon={Book}>Learn</TitleWithIcon>,
   },

diff --git a/app/en/guides/_meta.tsx → app/en/build/_meta.tsx b/app/en/guides/_meta.tsx → app/en/build/_meta.tsx
@@ -1,17 +1,8 @@
 import type { MetaRecord } from "nextra";
 
 export const meta: MetaRecord = {
-  "audit-logs": {
-    title: "Audit Logs",
-  },
-  "contextual-access": {
-    title: "Contextual Access",
-  },
-  "mcp-gateways": {
-    title: "MCP Gateways",
-  },
-  "user-sources": {
-    title: "User Sources",
+  index: {
+    title: "Overview",
   },
   "tool-calling": {
     title: "Call tools",
@@ -22,8 +13,8 @@ export const meta: MetaRecord = {
   "user-facing-agents": {
     title: "User-facing agents",
   },
-  "deployment-hosting": {
-    title: "Deployment & hosting",
+  "arcade-deploy": {
+    title: "Arcade Deploy",
   },
 };
 

diff --git a/...deployment-hosting/arcade-deploy/page.mdx → app/en/build/arcade-deploy/page.mdx b/...deployment-hosting/arcade-deploy/page.mdx → app/en/build/arcade-deploy/page.mdx
@@ -11,7 +11,7 @@ import { SignupLink } from "@/app/_components/analytics";
 Running your MCP servers locally is very convenient during development and testing. Once your MCP server is mature, however, you may want to access it from any MCP client, or to facilitate multi-user support. Doing all that from your computer comes with the complexity of running and maintaining a server, handling auth and high availability for all your users and all the integrations you want to support. Arcade Deploy takes care of all that for you. Your MCP server will be registered to Arcade, adding all the tools you created to the larger tool catalog. From there, you can create MCP Gateways to pick and choose which tools you want to use in your MCP clients, which can be from any connected MCP server.
 
 <Callout type="info">
-Arcade Deploy hosts *your* MCP server on Arcade Cloud. It's a feature for serving tools — not a way to deploy the Arcade platform. For a full platform deployment, see the [marketplace guides](/guides/deployment-hosting) or [self-host with Helm](/guides/deployment-hosting/helm).
+Arcade Deploy hosts *your* MCP server on Arcade Cloud. It's a feature for serving tools — not a way to deploy the Arcade platform. For a full platform deployment, see the [marketplace guides](/operate/deploy) or [self-host with Helm](/operate/deploy/helm).
 </Callout>
 
 <GuideOverview>
@@ -25,7 +25,7 @@ This guide shows you how to deploy your MCP Server with Arcade Deploy.
 
 - <DashboardLink path="register" />
 - [uv package manager](https://docs.astral.sh/uv/getting-started/installation/)
-- [Create an MCP Server](/guides/create-tools/tool-basics/build-mcp-server)
+- [Create an MCP Server](/build/create-tools/tool-basics/build-mcp-server)
 
 </GuideOverview.Prerequisites>
 
@@ -64,7 +64,7 @@ This guide shows you how to deploy your MCP Server with Arcade Deploy.
 
 ## Create an MCP server using Arcade MCP
 
-If you have not created an MCP server yet, then follow the steps outlined in [this guide](/guides/create-tools/tool-basics/build-mcp-server) before deploying.
+If you have not created an MCP server yet, then follow the steps outlined in [this guide](/build/create-tools/tool-basics/build-mcp-server) before deploying.
 
 ## Deploy your MCP Server
 
@@ -152,11 +152,11 @@ Navigate to the [Servers](https://api.arcade.dev/dashboard/servers) page in your
 - Test and execute all the tools
 - Manage users connected to the Auth providers
 - Manage the secrets for the server
-- Create [MCP Gateways](/guides/mcp-gateways)
+- Create [MCP Gateways](/operate/governance/mcp-gateways)
 
 ## Create an MCP Gateway to call the tools in your MCP Server
 
-Once the MCP server is deployed to Arcade, all the tools in the server will be available in the [tool catalog](https://api.arcade.dev/dashboard/tools) page in your Arcade dashboard. To call the tools from an MCP client, you first need to [create an MCP Gateway](/guides/mcp-gateways) to pick and choose which tools you want to use in your MCP clients.
+Once the MCP server is deployed to Arcade, all the tools in the server will be available in the [tool catalog](https://api.arcade.dev/dashboard/tools) page in your Arcade dashboard. To call the tools from an MCP client, you first need to [create an MCP Gateway](/operate/governance/mcp-gateways) to pick and choose which tools you want to use in your MCP clients.
 
 When creating an MCP gateway, you can select the tools you want to include in the Gateway from any MCP Servers available to the project, including the one you just deployed.
 

diff --git a/app/en/guides/create-tools/_meta.tsx → app/en/build/create-tools/_meta.tsx b/app/en/guides/create-tools/_meta.tsx → app/en/build/create-tools/_meta.tsx
@@ -3,18 +3,18 @@ import type { MetaRecord } from "nextra";
 export const meta: MetaRecord = {
   "tool-basics": {
     title: "Build a tool",
-    href: "/guides/create-tools/tool-basics",
+    href: "/build/create-tools/tool-basics",
   },
   "evaluate-tools": {
     title: "Evaluate tools",
-    href: "/guides/create-tools/evaluate-tools",
+    href: "/build/create-tools/evaluate-tools",
   },
   improve: {
     title: "Improve an existing toolkit",
   },
   "error-handling": {
     title: "Handle errors",
-    href: "/guides/create-tools/error-handling",
+    href: "/build/create-tools/error-handling",
   },
   "secure-your-server": {
     title: "Secure your server",

diff --git a/...des/create-tools/error-handling/_meta.tsx → ...ild/create-tools/error-handling/_meta.tsx b/...des/create-tools/error-handling/_meta.tsx → ...ild/create-tools/error-handling/_meta.tsx
diff --git a/...ides/create-tools/error-handling/page.mdx → ...uild/create-tools/error-handling/page.mdx b/...ides/create-tools/error-handling/page.mdx → ...uild/create-tools/error-handling/page.mdx
@@ -12,4 +12,4 @@ Learn how to implement robust error handling that improves user experience and e
 
 Robust error handling is crucial for building reliable tools that provide great user experiences. Arcade provides a comprehensive error handling system that helps you manage different types of errors gracefully.
 
-<SubpageList basePath="/guides/create-tools/error-handling" meta={meta} />
+<SubpageList basePath="/build/create-tools/error-handling" meta={meta} />
diff --git a/...tools/error-handling/retry-tools/page.mdx → ...tools/error-handling/retry-tools/page.mdx b/...tools/error-handling/retry-tools/page.mdx → ...tools/error-handling/retry-tools/page.mdx
diff --git a/...rror-handling/useful-tool-errors/page.mdx → ...rror-handling/useful-tool-errors/page.mdx b/...rror-handling/useful-tool-errors/page.mdx → ...rror-handling/useful-tool-errors/page.mdx
@@ -102,7 +102,7 @@ def search_posts(
     # ... rest of implementation
 ```
 
-Learn more about [RetryableToolError](/guides/create-tools/error-handling/retry-tools).
+Learn more about [RetryableToolError](/build/create-tools/error-handling/retry-tools).
 
 ### ContextRequiredToolError
 
@@ -234,4 +234,4 @@ This will raise a `ToolOutputError` because the return type doesn't match the an
 
 ## Handling tool errors in agents
 
-To learn more about how to handle tool errors in your Agent, see the [Use Tools](/guides/tool-calling/error-handling) section.
+To learn more about how to handle tool errors in your Agent, see the [Use Tools](/build/tool-calling/error-handling) section.
diff --git a/...des/create-tools/evaluate-tools/_meta.tsx → ...ild/create-tools/evaluate-tools/_meta.tsx b/...des/create-tools/evaluate-tools/_meta.tsx → ...ild/create-tools/evaluate-tools/_meta.tsx
diff --git a/...ools/evaluate-tools/capture-mode/page.mdx → ...ools/evaluate-tools/capture-mode/page.mdx b/...ools/evaluate-tools/capture-mode/page.mdx → ...ools/evaluate-tools/capture-mode/page.mdx
@@ -383,7 +383,7 @@ ExpectedMCPToolCall("GetWeather", {"location": "Tokyo", "units": "celsius"})
 
 ### Step 3: Add critics
 
-Add critics to validate parameters. See [Critics](/guides/create-tools/evaluate-tools/create-evaluation-suite#critics) for options.
+Add critics to validate parameters. See [Critics](/build/create-tools/evaluate-tools/create-evaluation-suite#critics) for options.
 
 ### Step 4: Run evaluations
 
@@ -441,5 +441,5 @@ suite = EvalSuite(
 
 ## Next steps
 
-- Learn about [comparative evaluations](/guides/create-tools/evaluate-tools/comparative-evaluations) to compare tool sources
-- [Create evaluation suites](/guides/create-tools/evaluate-tools/create-evaluation-suite) with expectations
+- Learn about [comparative evaluations](/build/create-tools/evaluate-tools/comparative-evaluations) to compare tool sources
+- [Create evaluation suites](/build/create-tools/evaluate-tools/create-evaluation-suite) with expectations
diff --git a/...te-tools/comparative-evaluations/page.mdx → ...te-tools/comparative-evaluations/page.mdx b/...te-tools/comparative-evaluations/page.mdx → ...te-tools/comparative-evaluations/page.mdx
@@ -522,7 +522,7 @@ Combine comparative tracks with multiple models:
 arcade evals . -p openai:gpt-4o,gpt-4o-mini -p anthropic:claude-sonnet-4-5-20250929
 ```
 
-Multi-run flags (`--num-runs`, `--seed`, `--multi-run-pass-rule`) also work with comparative tracks. See [Run evaluations](/guides/create-tools/evaluate-tools/run-evaluations).
+Multi-run flags (`--num-runs`, `--seed`, `--multi-run-pass-rule`) also work with comparative tracks. See [Run evaluations](/build/create-tools/evaluate-tools/run-evaluations).
 
 Results show:
 
@@ -752,6 +752,6 @@ suite.add_tool_catalog(catalog_v2, track="Python v2")
 
 ## Next steps
 
-- [Create an evaluation suite](/guides/create-tools/evaluate-tools/create-evaluation-suite) with tracks
-- Use [capture mode](/guides/create-tools/evaluate-tools/capture-mode) to discover track-specific tool calls
-- [Run evaluations](/guides/create-tools/evaluate-tools/run-evaluations) with multiple models and tracks
+- [Create an evaluation suite](/build/create-tools/evaluate-tools/create-evaluation-suite) with tracks
+- Use [capture mode](/build/create-tools/evaluate-tools/capture-mode) to discover track-specific tool calls
+- [Run evaluations](/build/create-tools/evaluate-tools/run-evaluations) with multiple models and tracks
diff --git a/...te-tools/create-evaluation-suite/page.mdx → ...te-tools/create-evaluation-suite/page.mdx b/...te-tools/create-evaluation-suite/page.mdx → ...te-tools/create-evaluation-suite/page.mdx
@@ -13,7 +13,7 @@ import { Steps, Tabs, Callout } from "nextra/components";
 
 ### Prerequisites
 
-- [Create an MCP Server](/guides/create-tools/tool-basics/build-mcp-server)
+- [Create an MCP Server](/build/create-tools/tool-basics/build-mcp-server)
 - Install the evaluation dependencies:
 
 <Tabs items={["uv", "pip"]} storageKey="packageManager">
@@ -164,7 +164,7 @@ arcade evals . --num-runs 3 --seed random --multi-run-pass-rule majority
   </Tabs.Tab>
 </Tabs>
 
-See [Run evaluations](/guides/create-tools/evaluate-tools/run-evaluations) for all available options.
+See [Run evaluations](/build/create-tools/evaluate-tools/run-evaluations) for all available options.
 
 ### Understand the results
 
@@ -380,6 +380,6 @@ If you want stricter suites, increase thresholds (for example `fail_threshold=0.
 
 ## Next steps
 
-- Learn how to [run evaluations with different providers](/guides/create-tools/evaluate-tools/run-evaluations)
-- Explore [capture mode](/guides/create-tools/evaluate-tools/capture-mode) to record tool calls
-- Compare tool sources with [comparative evaluations](/guides/create-tools/evaluate-tools/comparative-evaluations)
+- Learn how to [run evaluations with different providers](/build/create-tools/evaluate-tools/run-evaluations)
+- Explore [capture mode](/build/create-tools/evaluate-tools/capture-mode) to record tool calls
+- Compare tool sources with [comparative evaluations](/build/create-tools/evaluate-tools/comparative-evaluations)
diff --git a/...ides/create-tools/evaluate-tools/page.mdx → ...uild/create-tools/evaluate-tools/page.mdx b/...ides/create-tools/evaluate-tools/page.mdx → ...uild/create-tools/evaluate-tools/page.mdx
@@ -10,4 +10,4 @@ import meta from './_meta';
 
 Learn how to systematically test and improve your tools to ensure they work reliably in production. Use these techniques after you've built your initial tools to validate their performance and guide iterative improvements.
 
-<SubpageList basePath="/guides/create-tools/evaluate-tools" meta={meta} />
+<SubpageList basePath="/build/create-tools/evaluate-tools" meta={meta} />
diff --git a/...s/evaluate-tools/run-evaluations/page.mdx → ...s/evaluate-tools/run-evaluations/page.mdx b/...s/evaluate-tools/run-evaluations/page.mdx → ...s/evaluate-tools/run-evaluations/page.mdx
@@ -151,7 +151,7 @@ Capture mode is useful for:
 - Debugging model behavior
 - Understanding tool call patterns
 
-See [Capture mode](/guides/create-tools/evaluate-tools/capture-mode) for details.
+See [Capture mode](/build/create-tools/evaluate-tools/capture-mode) for details.
 
 ## Output formats
 
@@ -497,5 +497,5 @@ Ensure your evaluation files:
 
 ## Next steps
 
-- Explore [capture mode](/guides/create-tools/evaluate-tools/capture-mode) for recording tool calls
-- Learn about [comparative evaluations](/guides/create-tools/evaluate-tools/comparative-evaluations) for comparing tool sources
+- Explore [capture mode](/build/create-tools/evaluate-tools/capture-mode) for recording tool calls
+- Learn about [comparative evaluations](/build/create-tools/evaluate-tools/comparative-evaluations) for comparing tool sources
diff --git a/...ools/evaluate-tools/why-evaluate/page.mdx → ...ools/evaluate-tools/why-evaluate/page.mdx b/...ools/evaluate-tools/why-evaluate/page.mdx → ...ools/evaluate-tools/why-evaluate/page.mdx
@@ -65,23 +65,23 @@ FAILED Wrong tool selected -- Score: 50.00%
 
 ## Next steps
 
-- [Create an evaluation suite](/guides/create-tools/evaluate-tools/create-evaluation-suite) to start testing your tools
-- [Run evaluations](/guides/create-tools/evaluate-tools/run-evaluations) with multiple providers
-- Explore [capture mode](/guides/create-tools/evaluate-tools/capture-mode) to bootstrap test expectations
-- Compare tool sources with [comparative evaluations](/guides/create-tools/evaluate-tools/comparative-evaluations)
+- [Create an evaluation suite](/build/create-tools/evaluate-tools/create-evaluation-suite) to start testing your tools
+- [Run evaluations](/build/create-tools/evaluate-tools/run-evaluations) with multiple providers
+- Explore [capture mode](/build/create-tools/evaluate-tools/capture-mode) to bootstrap test expectations
+- Compare tool sources with [comparative evaluations](/build/create-tools/evaluate-tools/comparative-evaluations)
 
 ## Advanced features
 
 Once you're comfortable with basic evaluations, explore these advanced capabilities:
 
 ### Capture mode
 
-Record tool calls without scoring to discover what models actually call. Useful for bootstrapping test expectations and debugging. [Learn more →](/guides/create-tools/evaluate-tools/capture-mode)
+Record tool calls without scoring to discover what models actually call. Useful for bootstrapping test expectations and debugging. [Learn more →](/build/create-tools/evaluate-tools/capture-mode)
 
 ### Comparative evaluations
 
-Test the same cases against different tool sources (tracks) with isolated registries. Compare how models perform with different tool implementations. [Learn more →](/guides/create-tools/evaluate-tools/comparative-evaluations)
+Test the same cases against different tool sources (tracks) with isolated registries. Compare how models perform with different tool implementations. [Learn more →](/build/create-tools/evaluate-tools/comparative-evaluations)
 
 ### Output formats
 
-Save results in multiple formats (txt, md, html, json) for reporting and analysis. Specify output files with extensions or use no extension for all formats. [Learn more →](/guides/create-tools/evaluate-tools/run-evaluations#output-formats)
+Save results in multiple formats (txt, md, html, json) for reporting and analysis. Specify output files with extensions or use no extension for all formats. [Learn more →](/build/create-tools/evaluate-tools/run-evaluations#output-formats)
diff --git a/...ate-tools/improve/types-of-tools/page.mdx → ...ate-tools/improve/types-of-tools/page.mdx b/...ate-tools/improve/types-of-tools/page.mdx → ...ate-tools/improve/types-of-tools/page.mdx
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,4 +12,4 @@ Learn how to implement robust error handling that improves user experience and e

		Robust error handling is crucial for building reliable tools that provide great user experiences. Arcade provides a comprehensive error handling system that helps you manage different types of errors gracefully.

		<SubpageList basePath="/guides/create-tools/error-handling" meta={meta} />
		<SubpageList basePath="/build/create-tools/error-handling" meta={meta} />
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,4 +10,4 @@ import meta from './_meta';

		Learn how to systematically test and improve your tools to ensure they work reliably in production. Use these techniques after you've built your initial tools to validate their performance and guide iterative improvements.

		<SubpageList basePath="/guides/create-tools/evaluate-tools" meta={meta} />
		<SubpageList basePath="/build/create-tools/evaluate-tools" meta={meta} />