[GRO-303] DO NOT MERGE ME docs(agent-plugin): add install guides for the Arcade agent plugin

app/en/get-started/_meta.tsx

@@ -2,6 +2,7 @@ import type { MetaRecord } from "nextra";
 
 export const meta: MetaRecord = {
   "about-arcade": "About Arcade",
+  "agent-plugin": "Agent Plugin",
   setup: "Setup",
   quickstarts: "Quickstarts",
   "agent-frameworks": "Agent Frameworks",

app/en/get-started/agent-plugin/_meta.tsx

@@ -0,0 +1,15 @@
+import type { MetaRecord } from "nextra";
+
+export const meta: MetaRecord = {
+  index: {
+    title: "Overview",
+  },
+  "tools-only": {
+    title: "Tools-only MCP server",
+  },
+  "team-rollout": {
+    title: "From personal use to team rollout",
+  },
+};
+
+export default meta;

app/en/get-started/agent-plugin/page.mdx

@@ -0,0 +1,127 @@
+---
+title: "Install the Arcade agent plugin"
+description: "Install Arcade in Cursor, Claude Code, VS Code, GitHub Copilot CLI, or Codex with one command. Your agent gets tools for every app you connect, with browser sign-in and no API keys."
+---
+
+import { Callout } from "nextra/components";
+import { SignupLink } from "@/app/_components/analytics";
+
+# Install the Arcade agent plugin
+
+The Arcade agent plugin puts Arcade inside your agent with one command. Your agent gains access to thousands of tools for email, calendar, chat, issues, docs, and dozens of other apps. You authorize each app in the browser the first time it comes up. No API keys to create, no gateway to configure.
+
+<GuideOverview>
+<GuideOverview.Outcomes>
+
+Install the Arcade agent plugin in your agent and run your first task against a connected app.
+
+</GuideOverview.Outcomes>
+
+<GuideOverview.Prerequisites>
+
+1. [Node.js](https://nodejs.org) so you can run `npx`
+2. An agent with [plugins](https://agent-plugins.org) support: Cursor, Claude Code, VS Code, GitHub Copilot CLI, or Codex
+3. An <SignupLink linkLocation="docs:agent-plugin-install">Arcade account</SignupLink>
+
+</GuideOverview.Prerequisites>
+
+</GuideOverview>
+
+<Callout type="info">
+  The plugin is built for personal use. When you are ready to put a workflow in
+  front of a team, read [from personal use to team
+  rollout](/get-started/agent-plugin/team-rollout). You will want your own [MCP
+  Gateway](/operate/governance/mcp-gateways) with a curated tool list and your
+  own identity provider.
+</Callout>
+
+## Install
+
+```bash
+{{ARCADE_PLUGIN_INSTALL_COMMAND}}
+```
+
+The CLI detects the supported agents on your machine and installs to each one. To install to a single agent, pass `--target`:
+
+```bash
+{{ARCADE_PLUGIN_INSTALL_COMMAND}} --target cursor
+{{ARCADE_PLUGIN_INSTALL_COMMAND}} --target claude-code
+{{ARCADE_PLUGIN_INSTALL_COMMAND}} --target vscode
+{{ARCADE_PLUGIN_INSTALL_COMMAND}} --target copilot
+{{ARCADE_PLUGIN_INSTALL_COMMAND}} --target codex
+```
+
+To see what an install would write without changing anything:
+
+```bash
+npx plugins discover {{ARCADE_PLUGIN_REPO}}
+```
+
+Reload your agent afterwards if it does not pick up the plugin on its own. A couple of agents gate plugins behind a setting. Claude Code may ask you to enable it with `claude plugin`, and VS Code needs `chat.plugins.enabled` set to `true`.
+
+Two things worth knowing if you use more than one agent. Codex and ChatGPT share a plugin directory, so one install covers both. And VS Code can discover a copy installed through GitHub Copilot CLI, so install in one place rather than both.
+
+// todo: claude mcpb instructions
+
+Using a client that does not load plugins? Those connect to the same gateway as a [tools-only MCP server](/get-started/agent-plugin/tools-only).
+
+## Sign in
+
+Authentication happens in two layers:
+
+1. **Into the gateway.** Your client will ask you to authenticate when it first connects. You sign in to Arcade in the browser, and the client can reach the gateway from then on.
+2. **Into each app.** When a task needs Gmail, Slack, Linear, or anything else, your agent hands you a link that grants the scopes that task requires. Approve it once and Arcade holds the token for that app. You won't need to authenticate that service again unless a later task requires greater scopes.
+
+You never give your agent an API key or a password for either layer. Ask your agent to run `/arcade-status` to see what applications are currently enabled , or `/arcade-connect google` to authorize an app with the widest possible scope before you need it.
+
+All of your tool calls, tokens, and secrets route through your own Arcade project, isolated from every other user of that gateway. No one else's agent can ever reach your apps, tools, or tokens.
+
+Every Arcade gateway works this way, not just the one in the plugin. [Server-level and tool-level authorization](/learn/server-level-vs-tool-level-auth) goes deeper on the split.
+
+## What you get in each agent
+
+Every install connects to the same Arcade gateway and gets the same tools. What differs is how much of the rest of the plugin each agent can load.
+
+| Agent                |     Tools      | Skills | Subagent | Commands | Rule | Hooks |
+| -------------------- | :------------: | :----: | :------: | :------: | :--: | :---: | --- | -------------- |
+| Cursor               |       ✅       |   2    |    ✅    |    3     |  ✅  |  ✅   |
+| Claude Code          |       ✅       |   2    |    ✅    |    3     |  —   |  ✅   |
+| Claude Cowork        |       ✅       |   2    |    ✅    |    3     |  —   |  ✅   |
+| GitHub Copilot CLI   |       ✅       |   2    |    ✅    |    —     |  —   |   —   |
+| VS Code              |       ✅       |   2    |    —     |    —     |  —   |   —   |
+| Codex and ChatGPT    |       ✅       |   2    |    —     |    —     |  —   |   —   |
+| Any other MCP client |       ✅       |   —    |    —     |    —     |  —   |   —   |
+| //                   | Claude Desktop |   ✅   |    —     |    —     |  —   |   —   | —   | TODO: not true |
+
+Here is what each of those is for.
+
+**Commands** are the part you type. `/arcade-status` reports whether the gateway is reachable, whether you have signed in, and which apps you have authorized. `/arcade-connect <app>` authorizes an app on demand, so you are not interrupted mid-task. `/arcade-apps` lists what you have connected and lets you disconnect one.
+
+**Skills** are instructions your agent reads on its own, so you never have to invoke them. `try-arcade` teaches it to turn a request like "reply to that thread" into the right sequence of tool calls across your apps. `scale-arcade` handles the other kind of question, the one about moving a workflow onto a team gateway, and it walks you through the decisions on [this page](/get-started/agent-plugin/team-rollout) against your own project.
+
+**The subagent**, `arcade-operator`, runs an app task in its own context and reports back just the result. Arcade exposes a lot of tools, and searching them fills a conversation with noise that pushes out your actual work. The operator absorbs that.
+
+**The rule and hooks** are Cursor and Claude Code specific. They tell your agent that Arcade exists and when reaching for it is the right move, which is the difference between a tool that sits unused and one your agent actually picks up.
+
+The columns thin out because the [Agent Plugins](https://agent-plugins.org) 1.0 specification only makes skills and MCP servers portable. Commands, subagents, hooks, and editor rules are specific to each agent, so the plugin ships them where the agents that support them will find them.
+
+## Try it
+
+The Arcade Agent Plugin exposes hundreds of tools from our catalog that need zero additional configuration. Try asking your agent:
+
+- "Send a summary of tomorrow's calendar events to me on Slack."
+- "Read my Granola notes from last week, check them against Linear, and file anything I promised that is not a ticket yet. Wait for me before creating anything."
+- "Find unread mail that needs a reply. Look the sender up in HubSpot if you can, draft a response, and Slack me the draft before sending."
+- "Pull my open GitHub pull requests, my Linear issues, and tomorrow's calendar. Write a standup update and send it to me on Slack."
+- "Search my Drive and Notion for the latest product spec, then drop a one-paragraph summary in Slack."
+
+Or ask "What can Arcade do?" and pick a workflow from the answer.
+
+\
+
+## Next steps
+
+- [From personal use to team rollout](/get-started/agent-plugin/team-rollout): move a workflow onto your own gateway
+- [Connect to MCP clients](/get-started/mcp-clients): configure a client against a gateway you control
+- [Integrations catalog](/resources/integrations): every app and toolkit Arcade supports
+- [Agentic development](/get-started/setup/connect-arcade-docs): point your agent at these docs with `llms.txt`

app/en/get-started/agent-plugin/team-rollout/page.mdx

@@ -0,0 +1,55 @@
+---
+title: "From personal use to team rollout"
+description: "What changes when an Arcade workflow you proved with the agent plugin becomes something a team depends on: your own MCP Gateway, a curated tool list, and your own identity provider."
+---
+
+import { Callout } from "nextra/components";
+
+# From personal use to team rollout
+
+The [agent plugin](/get-started/agent-plugin) serves one person working on their own. Every install points at the same global gateway URL, and that is where the sharing ends. Your tool calls, tokens, and secrets route through your own Arcade project, isolated from every other user of that gateway. No one else's agent can reach your Gmail, and yours cannot reach theirs.
+
+What the plugin gives you is a broad tool selection and an identity that is yours alone, which is what you want for your own work.
+
+Once a team depends on that workflow, three questions you never had to answer start to matter:
+
+1. Where does your team connect?
+2. Which tools can they call?
+3. Who is each end user?
+
+Each one has a section below, in that order.
+
+<Callout type="info">
+  If your agent loaded the plugin's skills, ask it to run `/scale-arcade`. The
+  skill walks through the same decisions interactively against your own
+  workspace.
+</Callout>
+
+## Where does your team connect?
+
+An [MCP Gateway](/operate/governance/mcp-gateways) is the endpoint your team's clients connect to, and it is where you decide what those clients can do. Create one per project in the [Arcade dashboard](https://app.arcade.dev) so each project gets a URL you control, its own tool list, and its own audit trail.
+
+Clients connect to it exactly the way they connected to the plugin's gateway. See the [MCP client guides](/get-started/mcp-clients) for Cursor, Claude Code, Claude Desktop, VS Code, and Copilot.
+
+## Which tools can they call?
+
+The gateway is the filter that decides which tools reach your agent. Open the **Allowed Tools** picker on your gateway and select across everything in scope: Arcade-hosted toolkits from the [integrations catalog](/resources/integrations), [remote MCP servers](/operate/governance/remote-mcp-servers) you register, and your own [custom MCP servers](/build/create-tools/tool-basics/build-mcp-server) deployed with [Arcade Deploy](/build/arcade-deploy).
+
+A smaller, deliberate tool list makes agents more accurate, not less capable. Save the gateway and connected clients see the new list on their next request, with no restart.
+
+Beyond the allowlist, [contextual access](/operate/governance/contextual-access) lets you allow or deny each individual tool call as it arrives, and [audit logs](/operate/governance/audit-logs) and [tool executions](/operate/governance/tool-executions) show you what actually ran.
+
+## Who is each end user?
+
+When you are the only user, signing in to each app yourself is enough. In production, each of your end users needs their own authorization, so an agent acting for one person can never reach another person's data.
+
+Configure a [User Source](/operate/identity/user-sources) on your gateway and Arcade redirects each end user to your existing identity provider, whether that is Entra ID, Okta, Auth0, Clerk, or another OIDC provider, then identifies them by an OIDC subject claim.
+
+## Building your own product?
+
+Connecting a client to a gateway takes the least work, and for many teams it is the whole rollout. When you are building your own product rather than configuring an agent, call Arcade directly instead:
+
+- [Arcade API reference](/references/api): the REST surface for tool calling and authorization
+- [Agent frameworks](/get-started/agent-frameworks) for LangChain, CrewAI, OpenAI Agents, Google ADK, Mastra, Vercel AI SDK, and more
+- [Get an API key](/get-started/setup/api-keys): required once you are calling Arcade from your own code
+- [Build user-facing agents](/build/user-facing-agents): patterns for handling authorization on behalf of your users

app/en/get-started/agent-plugin/tools-only/_meta.tsx

@@ -0,0 +1,15 @@
+import type { MetaRecord } from "nextra";
+
+export const meta: MetaRecord = {
+  index: {
+    title: "Overview",
+  },
+  "claude-desktop": {
+    title: "Claude Desktop",
+  },
+  "any-mcp-client": {
+    title: "Any MCP client",
+  },
+};
+
+export default meta;

app/en/get-started/agent-plugin/tools-only/any-mcp-client/page.mdx

@@ -0,0 +1,44 @@
+---
+title: "Install Arcade in any MCP client"
+description: "Point any Streamable HTTP MCP client at the Arcade gateway to get tools for every app you connect, with no API key and no plugin install."
+---
+
+# Install Arcade in any MCP client
+
+Any client that speaks the Streamable HTTP MCP transport can use Arcade tools, OpenCode included. Add this as an MCP server:
+
+```text
+{{ARCADE_PLUGIN_GATEWAY_URL}}
+```
+
+Your agent gets every tool on the gateway. Nothing else about how you use it changes.
+
+## One-click links
+
+Cursor and VS Code can add the gateway without editing any config:
+
+- **Cursor:** use [this link]({{ARCADE_PLUGIN_CURSOR_INSTALL_LINK}}) for a one-click MCP install.
+- **VS Code:** use [this link]({{ARCADE_PLUGIN_VSCODE_INSTALL_LINK}}) for a one-click MCP install.
+
+Both of those clients also load the full plugin, so use these only if you want the tools on their own. [Install the agent plugin](/get-started/agent-plugin) for the rest.
+
+## Sign in
+
+Your client signs you in to Arcade when it first connects, and each app gets authorized the first time a task needs it. See [signing in](/get-started/agent-plugin/tools-only#sign-in) for how the two layers fit together.
+
+## Try it
+
+Ask your agent for an outcome rather than naming a tool. This gateway has every [optimized toolkit](/resources/integrations). The first time a task needs an app you have not authorized, your agent hands you a link. Approve it and the rest of the task continues, including steps that land in a different app.
+
+Swap the app names for whatever you actually use:
+
+- "Send a summary of tomorrow's calendar events to me on Slack."
+- "Read my Granola notes from last week, check them against Linear, and file anything I promised that is not a ticket yet. Wait for me before creating anything."
+- "Find unread mail that needs a reply. Draft a response, Slack me the draft, and wait for me before sending it."
+- "What apps can Arcade use?"
+
+## Next steps
+
+- [Tools-only MCP server](/get-started/agent-plugin/tools-only): what you give up by skipping the plugin
+- [Install the agent plugin](/get-started/agent-plugin): one command for Cursor, Claude Code, VS Code, Copilot CLI, and Codex
+- [Connect to MCP clients](/get-started/mcp-clients): point a client at a gateway you control, with your own tool list

app/en/get-started/agent-plugin/tools-only/claude-desktop/page.mdx

@@ -0,0 +1,70 @@
+---
+title: "Install Arcade in Claude Desktop"
+description: "Install the Arcade bundle in Claude Desktop with one download, or add the gateway as a custom connector, so Claude can act across the apps you connect."
+---
+
+import { Callout } from "nextra/components";
+import { SignupLink } from "@/app/_components/analytics";
+
+# Install Arcade in Claude Desktop
+
+Claude Desktop installs Arcade from a bundle rather than the `npx` command the coding agents use. Download it, open it, and Claude Desktop handles the rest. No API keys, and you authorize each app in the browser the first time it comes up.
+
+<GuideOverview>
+<GuideOverview.Outcomes>
+
+Install the Arcade bundle in Claude Desktop and run a task against one of your apps.
+
+</GuideOverview.Outcomes>
+
+<GuideOverview.Prerequisites>
+
+1. Claude Desktop, updated to a version that supports extensions
+2. An <SignupLink linkLocation="docs:agent-plugin-claude-desktop">Arcade account</SignupLink>
+
+</GuideOverview.Prerequisites>
+
+</GuideOverview>
+
+<Callout type="info">
+  Using Cowork or Claude Code inside the Claude desktop app? Those load the full
+  agent plugin, with skills, commands, and the `arcade-operator` subagent.
+  Install it with [one command](/get-started/agent-plugin) instead.
+</Callout>
+
+## Install the bundle
+
+1. Download [the Arcade bundle]({{ARCADE_PLUGIN_MCPB_URL}})
+2. Open the downloaded `.mcpb` file, and Claude Desktop offers to install it
+3. Confirm the install, then start a new conversation
+
+## Sign in
+
+Connecting Arcade signs you in and links Claude Desktop to the gateway. After that, the first time Claude reaches for an app, it returns a browser link asking you to authorize that app. Approve it and Arcade holds the token, so you only do this once per app. See [signing in](/get-started/agent-plugin/tools-only#sign-in) for how the two layers fit together.
+
+## Try it
+
+Ask Claude for an outcome rather than naming a tool. This gateway has every [optimized toolkit](/resources/integrations). The first time a task needs an app you have not authorized, Claude hands you a link. Approve it and the rest of the task continues, including steps that land in a different app.
+
+Swap the app names for whatever you actually use:
+
+- "Send a summary of tomorrow's calendar events to me on Slack."
+- "Read my Granola notes from last week, check them against Linear, and file anything I promised that is not a ticket yet. Wait for me before creating anything."
+- "Find unread mail that needs a reply. Draft a response, Slack me the draft, and wait for me before sending it."
+- "What apps can Arcade use?"
+
+## Add the gateway by hand instead
+
+If you would rather not install a bundle, Claude Desktop can reach the same gateway as a custom connector. Open **Settings → Connectors**, click **Add custom connector**, and paste:
+
+```text
+{{ARCADE_PLUGIN_GATEWAY_URL}}
+```
+
+Save, then start a new conversation. You get the same tools this way; the bundle just saves you the trip through settings.
+
+## Next steps
+
+- [Tools-only MCP server](/get-started/agent-plugin/tools-only): what you give up by skipping the plugin
+- [Install the agent plugin](/get-started/agent-plugin): the full experience in Cursor, Claude Code, VS Code, Copilot CLI, or Codex
+- [Use Arcade in Claude Desktop with your own gateway](/get-started/mcp-clients/claude-desktop): pick exactly which tools Claude can call