@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.15

package/.docs/{guides/build-your-ui/copilotkit/overview.md → integrations/agentic-ui/copilotkit.md}

@@ -4,11 +4,11 @@
 
 [CopilotKit](https://www.copilotkit.ai/) provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build AI apps with bidirectional state synchronization and interactive UIs.
 
-CopilotKit talks to Mastra through the [AG-UI protocol](https://docs.ag-ui.com/). The `@ag-ui/mastra` package exposes your Mastra agents as an AG-UI endpoint, and CopilotKit's React hooks and components consume it. This unlocks a spectrum of experiences on top of ordinary chat: [generative UI, human-in-the-loop, and frontend tools](https://mastra.ai/guides/build-your-ui/copilotkit/generative-ui), plus deploying the same agent to [messaging channels like Slack](https://mastra.ai/guides/build-your-ui/copilotkit/channels).
+CopilotKit talks to Mastra through the [AG-UI protocol](https://docs.ag-ui.com/). The `@ag-ui/mastra` package exposes your Mastra agents as an AG-UI endpoint, and CopilotKit's React hooks and components consume it. This unlocks a spectrum of experiences on top of ordinary chat: [generative UI, human-in-the-loop, and frontend tools](#generative-ui), plus deploying the same agent to [messaging channels like Slack](#channels).
 
 Visit the [CopilotKit documentation](https://docs.copilotkit.ai/) to learn more about CopilotKit concepts, components, and advanced usage patterns.
 
-> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart) guide.
+> **Note:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart) guide.
 
 Visit Mastra's ["UI Dojo"](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
 
@@ -295,9 +295,175 @@ export default function Home() {
 
 For fully custom chat UIs (bring your own components), see [CopilotKit's headless UI guide](https://docs.copilotkit.ai/).
 
+## Generative UI
+
+Generative UI describes interfaces that agents help create and that users can interact with. CopilotKit organizes these interfaces along a single axis, the **generative UI spectrum**, which runs from author-controlled (you decide every pixel) to agent-invented (the agent owns the rendered surface). Your position on the axis is a trade-off between predictability and breadth.
+
+The spectrum has three tiers:
+
+| Tier            | Who controls the surface                                                                   | Primitives                                                           |
+| --------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| **Controlled**  | You wrote the component. The agent picks which one to use and what data to pass.           | Tool call rendering, state rendering, reasoning, components as tools |
+| **Declarative** | The agent emits a structured spec. The frontend composes it from a catalog you registered. | A2UI (fixed-schema and flexible variants)                            |
+| **Open-ended**  | The UI is invented elsewhere (an MCP server) and you sandbox it.                           | MCP Apps                                                             |
+
+Each tier is a Mastra agent exposed through `registerCopilotKit()` plus the matching CopilotKit hook on the frontend. For the full concept, see CopilotKit's [generative UI spectrum](https://www.copilotkit.ai/generative-ui-spectrum) and [generative UI overview](https://docs.copilotkit.ai/concepts/generative-ui-overview).
+
+> **Tip:** Mastra's [UI Dojo](https://ui-dojo.mastra.ai/) has working CopilotKit examples. Browse the source under `src/pages/copilot-kit`.
+
+### Controlled
+
+You provide a fixed set of components. The agent chooses which component to render and supplies its data. This predictable, brand-safe approach works well for high-traffic surfaces. The Controlled primitives use CopilotKit's v2 API, imported from `@copilotkit/react-core/v2`.
+
+#### Tool call rendering
+
+Render an agent's tool call as a React component. Define the agent and tool on the Mastra server as usual:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: 'Use the weatherTool to fetch current weather data.',
+  model: 'openai/gpt-5.6-sol',
+  tools: { weatherTool },
+})
+```
+
+On the frontend, register a renderer for the tool by name with `useRenderTool`. It's render-only (it doesn't execute the tool); the `render` function receives the tool call's `status` and, once the agent returns, its `result`:
+
+```tsx
+import { z } from 'zod'
+import { CopilotChat } from '@copilotkit/react-ui'
+import { CopilotKit, useRenderTool } from '@copilotkit/react-core/v2'
+import { Weather } from '@/components/weather'
+
+function Chat() {
+  useRenderTool(
+    {
+      name: 'weatherTool',
+      parameters: z.object({ location: z.string() }),
+      render: ({ status, result }) => {
+        if (status !== 'complete') {
+          return <div>Retrieving weather...</div>
+        }
+        return <Weather {...result} />
+      },
+    },
+    [],
+  )
+
+  return <CopilotChat labels={{ title: 'Weather Assistant' }} />
+}
+
+export default function Page() {
+  return (
+    <CopilotKit runtimeUrl="http://localhost:4111/copilotkit" agent="weatherAgent">
+      <Chat />
+    </CopilotKit>
+  )
+}
+```
+
+Because Mastra streams tool-call arguments incrementally, the `render` function is called repeatedly as the arguments arrive, so the UI can paint progressively while the agent works.
+
+#### Components as tools
+
+Register a React component and let the agent call it as a tool. CopilotKit renders it inline with typed props (defined with a Zod schema):
+
+```tsx
+import { z } from 'zod'
+import { useComponent } from '@copilotkit/react-core/v2'
+
+const schema = z.object({ text: z.string() })
+
+function Callout({ text }: z.infer<typeof schema>) {
+  return <div className="callout">{text}</div>
+}
+
+function Chat() {
+  useComponent({ name: 'callout', render: Callout, parameters: schema }, [])
+  return <CopilotChat labels={{ title: 'Assistant' }} />
+}
+```
+
+The agent invokes `callout` like any other tool, and CopilotKit renders `Callout` with the props it passed.
+
+#### State rendering
+
+Render UI from the agent's state and re-render as it streams. On Mastra, agent state is the agent's working memory, streamed to the client as it changes. Read it with `useAgent`; `agent.state` is reactive, so the component updates automatically:
+
+```tsx
+import { useAgent } from '@copilotkit/react-core/v2'
+
+function TaskBoard() {
+  const { agent } = useAgent()
+  const tasks = (agent.state.tasks as any[]) ?? []
+
+  return (
+    <ul>
+      {tasks.map((task, i) => (
+        <li key={i}>
+          {task.title}: {task.status}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+#### Reasoning
+
+Reasoning is zero-config: when your Mastra agent runs a reasoning-capable model, `CopilotChat` renders the model's thinking inline as a dedicated message type, with no extra code. To restyle it, pass your own component to the `reasoningMessage` slot on `CopilotChat`. See CopilotKit's [generative UI guides](https://docs.copilotkit.ai/) for details.
+
+### Declarative
+
+Instead of a fixed component per tool, you register a catalog of typed building blocks and the agent assembles them into a UI tree per request. CopilotKit calls this **A2UI** (Agent-to-UI), which has fixed-schema and flexible variants. It suits the long tail of secondary interactions where breadth matters more than pixel-perfection.
+
+The path of least resistance is to pass your catalog to the `<CopilotKit>` provider. That single prop enables A2UI rendering and injects the A2UI tool into your agent, so no backend change is needed:
+
+```tsx
+import { CopilotKit } from '@copilotkit/react-core/v2'
+import { myCatalog } from './a2ui-catalog'
+
+export default function Page() {
+  return (
+    <CopilotKit
+      runtimeUrl="http://localhost:4111/copilotkit"
+      agent="weatherAgent"
+      a2ui={{ catalog: myCatalog }}
+    >
+      {/* your app */}
+    </CopilotKit>
+  )
+}
+```
+
+The catalog defines the primitives (their schemas) and the renderers (how each primitive displays). In the fixed-schema variant, the components are pre-authored and the agent's tool only supplies data. The flexible variant lets the agent compose the tree more freely. See CopilotKit's [A2UI documentation](https://docs.copilotkit.ai/a2a/generative-ui/a2ui).
+
+### Open-ended
+
+At the far end of the spectrum, the agent owns the entire surface: the UI is invented elsewhere and sandboxed in your app. CopilotKit supports this through **MCP Apps**, where an MCP server provides UI that renders inside your application. This tier trades determinism for novelty and is the most experimental point on the spectrum.
+
+The path of least resistance keeps the frontend untouched: your existing `<CopilotKit>` provider is enough. On the backend, point `registerCopilotKit()` at one or more MCP servers with the `mcpApps` option (it's forwarded to the CopilotKit runtime):
+
+```typescript
+registerCopilotKit({
+  path: '/copilotkit',
+  resourceId: 'weatherAgent',
+  mcpApps: {
+    servers: [{ type: 'http', url: 'http://localhost:3108/mcp', serverId: 'my-server' }],
+  },
+})
+```
+
+When the agent calls an MCP App tool, CopilotKit fetches and renders that tool's UI in the chat with no additional frontend code. See CopilotKit's [MCP Apps documentation](https://docs.copilotkit.ai/agno/generative-ui/mcp-apps).
+
 ## App control and interactivity
 
-Beyond rendering agent output as UI (see [generative UI](https://mastra.ai/guides/build-your-ui/copilotkit/generative-ui)), CopilotKit lets the agent act on your application and pause for the user. Both patterns run against the same Mastra setup.
+Some capabilities sit next to the [generative UI](#generative-ui) spectrum rather than on it: they control your app or gate a run instead of rendering agent output. CopilotKit lets the agent act on your application and pause for the user. Both patterns run against the same Mastra setup.
 
 ### Frontend tools
 
@@ -333,6 +499,8 @@ export default function Page() {
 
 The matching Mastra agent is a normal agent instructed to call `colorChangeTool` with the requested color.
 
+CopilotKit treats frontend tools as part of its separate [App Control](https://docs.copilotkit.ai/) concept, alongside shared state and agent context.
+
 ### Human-in-the-loop
 
 Pause the agent mid-run and wait for the user to approve, edit, or reject before continuing. Use `useHumanInTheLoop`: its `render` function receives a `respond` callback, and the agent's run stays suspended until you call it.
@@ -379,6 +547,91 @@ Inside `StepsFeedback`, let the user toggle steps and then call `respond({ accep
 
 The example above uses a client tool: the agent calls `generate_task_steps` and the frontend fulfills it through `respond`. Mastra can also pause on the server, suspending a tool call before it executes so a human approves or supplies input. For that path, see Mastra's [Agent approval](https://mastra.ai/docs/agents/agent-approval) guide for the backend side and CopilotKit's [`useHumanInTheLoop`](https://docs.copilotkit.ai/reference/hooks/useHumanInTheLoop) reference for the frontend.
 
+## Channels
+
+The same Mastra agent that powers your in-app copilot can also run as a bot in messaging platforms. CopilotKit's Channels SDK connects your agent to Slack and other messaging platforms, with threads, tool calls, rich interactive messages, and human-in-the-loop approvals handled natively in the channel.
+
+> **Note:** Full platform setup lives in the [CopilotKit Channels documentation](https://docs.copilotkit.ai/slack/mastra). This section shows how Channels fit together with a Mastra agent.
+
+### How it fits together
+
+Your Mastra agent stays where it's deployed, exposed over AG-UI through `registerCopilotKit()`. A channel is a separate long-running process built with `@copilotkit/channels`: you attach one or more platform adapters and point the channel at your agent. `createChannel` takes an array of adapters, so a single process can serve several platforms at once.
+
+Install the SDK (batteries-included, every adapter):
+
+**npm**:
+
+```bash
+npm install @copilotkit/channels
+```
+
+**pnpm**:
+
+```bash
+pnpm add @copilotkit/channels
+```
+
+**Yarn**:
+
+```bash
+yarn add @copilotkit/channels
+```
+
+**Bun**:
+
+```bash
+bun add @copilotkit/channels
+```
+
+```typescript
+import { createChannel, Message, Section } from '@copilotkit/channels'
+import { slack } from '@copilotkit/channels/slack'
+import { mastraAgent } from './agent' // your AG-UI Mastra agent
+
+const channel = createChannel({
+  // Point the channel at your Mastra agent (an AbstractAgent, or a per-thread factory).
+  agent: mastraAgent,
+  adapters: [
+    slack({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      appToken: process.env.SLACK_APP_TOKEN!,
+    }),
+  ],
+})
+
+channel.onMention(async ({ thread }) => {
+  await thread.runAgent()
+})
+
+await channel.start()
+```
+
+The agent receives ordinary AG-UI input and emits ordinary AG-UI events; the platform mechanics stay behind the adapter, so the same Mastra agent runs unchanged across every channel. Rich messages are written as JSX and rendered to each platform's native format (Block Kit on Slack, for example), so an interactive card degrades gracefully where a platform has no equivalent.
+
+### Slack
+
+The [Slack quickstart](https://docs.copilotkit.ai/slack/mastra) takes you from zero to a bot you can `@`-mention in a channel, then adds an interactive button card. Slack runs over Socket Mode, which opens an outbound WebSocket to Slack, so no public URL or tunnel is required during development.
+
+Set the Slack credentials in your environment:
+
+- `SLACK_BOT_TOKEN`: Bot User OAuth token (`xoxb-...`)
+- `SLACK_APP_TOKEN`: App-level token with the `connections:write` scope (`xapp-...`)
+
+### Other platforms
+
+The Channels SDK isn't limited to Slack. Other platforms like Microsoft Teams run through the same `@copilotkit/channels` API: add the matching adapter to the `adapters` array and the rest of your agent code stays the same. See the [CopilotKit Channels documentation](https://docs.copilotkit.ai/slack/mastra) for the current platform list and per-platform setup.
+
+### Message pipeline and architecture
+
+Managed channels keep a deliberate credential split, which matters when your Mastra agent uses separate model keys and tools:
+
+- **You keep** the agent logic, model credentials, tools, and the channel process.
+- **CopilotKit Intelligence holds** the platform credentials, message delivery, registration, health, and reconnects.
+
+A turn begins when a user messages the app. Intelligence receives the platform event, and the gateway delivers the turn to your running channel process. Your Mastra agent runs and renders a reply. Intelligence then returns the reply as native platform content. Platform credentials never enter the agent process, and enterprise Intelligence can be self-hosted for data residency.
+
+> **Note:** By default, interactive actions live in memory and reset on restart. Back the channel with a durable action and state store (Redis or Postgres) so buttons and per-thread state survive restarts and span multiple instances.
+
 ## Configuration options
 
 Use these `registerCopilotKit()` options for the common integration points:
@@ -392,7 +645,7 @@ Use these `registerCopilotKit()` options for the common integration points:
 | `agents`         | Provide pre-constructed AG-UI agents instead of the agents registered on the Mastra instance. |
 | `tracingOptions` | Forward Mastra tracing options to each agent run.                                             |
 
-By default, the endpoint exposes every agent registered on the Mastra instance, and the frontend chooses one with the `agent` prop. Other CopilotKit runtime options are forwarded to the underlying runtime. For example, see [Open-ended generative UI](https://mastra.ai/guides/build-your-ui/copilotkit/generative-ui) for `mcpApps`.
+By default, the endpoint exposes every agent registered on the Mastra instance, and the frontend chooses one with the `agent` prop. Other CopilotKit runtime options are forwarded to the underlying runtime. For example, see [Open-ended generative UI](#open-ended) for `mcpApps`.
 
 ## Deployment
 

package/.docs/{docs/server → integrations}/auth/auth0.md

@@ -200,7 +200,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/{docs/server → integrations}/auth/clerk.md

@@ -61,7 +61,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+> **Note:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
 >
 > Visit [MastraAuthClerk](https://mastra.ai/reference/auth/clerk) for all available configuration options.
 
@@ -105,7 +105,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/{docs/server → integrations}/auth/firebase.md

@@ -200,7 +200,7 @@ export const createMastraClient = (idToken: string) => {
 }
 ```
 
-> **Info:** The ID token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The ID token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/{docs/server → integrations}/auth/okta.md

@@ -179,16 +179,35 @@ export const mastraClient = new MastraClient({
 
 ### Bearer token
 
-You can also pass an Okta access token as a Bearer token. The token is verified against Okta's JWKS endpoint:
+You can also pass an Okta token as a Bearer token. The token is verified against Okta's JWKS endpoint, and its `aud` claim must match the configured audience. The audience defaults to your client ID, and you can override it with the `audience` option or `OKTA_AUDIENCE`.
+
+Okta puts the client ID in the `aud` claim of **ID tokens**, so ID tokens work with the default. **Access tokens** carry the audience of the authorization server that issued them, so set the audience to match:
+
+- **Org authorization server** (the default, issuer `https://{domain}`): set the audience to `https://{domain}`.
+- **Custom authorization server** (issuer `https://{domain}/oauth2/{name}`): set the audience to the server's audience value from the Okta Admin Console, for example `api://default`.
+
+```env
+OKTA_AUDIENCE=https://dev-123456.okta.com
+```
+
+Pass an array to accept more than one audience, for example ID tokens from browsers and access tokens from service callers against the same provider:
+
+```typescript
+new MastraAuthOkta({
+  audience: ['your-client-id', 'https://dev-123456.okta.com'],
+})
+```
+
+> **Note:** `audience` applies only to Bearer tokens. The ID token exchanged during the SSO login flow is always verified against your client ID.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
 
-export const createMastraClient = (accessToken: string) => {
+export const createMastraClient = (token: string) => {
   return new MastraClient({
     baseUrl: 'http://localhost:4111',
     headers: {
-      Authorization: `Bearer ${accessToken}`,
+      Authorization: `Bearer ${token}`,
     },
   })
 }
@@ -213,7 +232,7 @@ console.log(response)
 ```bash
 curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-okta-access-token>" \
+  -H "Authorization: Bearer <your-okta-token>" \
   -d '{
     "messages": "Weather in London"
   }'
@@ -222,6 +241,7 @@ curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
 ## Troubleshooting
 
 - **401 on every request**: Verify your Okta domain, client ID, and client secret are correct. Check that the redirect URI in your Okta application matches `OKTA_REDIRECT_URI`.
+- **401 with `unexpected "aud" claim value` in the server logs**: The Bearer token's audience doesn't match the configured audience. This usually means you sent an access token while the audience is still the default client ID. Set `OKTA_AUDIENCE` to the audience of the authorization server that issued the token. See [Bearer token](#bearer-token).
 - **Cookies not sent cross-origin**: Set `credentials: "include"` in `MastraClient` and configure `server.cors` with your frontend origin and `credentials: true`.
 - **Session lost on restart**: Set `OKTA_COOKIE_PASSWORD` to a stable value (at least 32 characters). Without it, an auto-generated key is used that changes on each restart.
 - **RBAC returns empty permissions**: Verify `OKTA_API_TOKEN` is set and the token has permission to list user groups. Check that group names in `roleMapping` match your Okta group names exactly.

package/.docs/{docs/server → integrations}/auth/supabase.md

@@ -59,7 +59,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+> **Note:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
 >
 > Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
 
@@ -101,7 +101,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/{docs/server → integrations}/auth/workos.md

@@ -221,7 +221,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/{docs/browser → integrations/browsers}/agent-browser.md

@@ -104,7 +104,7 @@ This adds `browser_record` and `browser_record_caption` to the agent's toolset.
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
-- [Stagehand](https://mastra.ai/docs/browser/stagehand)
-- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
+- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
+- [Firecrawl](https://mastra.ai/integrations/browsers/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

package/.docs/{docs/browser → integrations/browsers}/browser-viewer.md

@@ -13,7 +13,7 @@ Use BrowserViewer when your agent drives a browser through a CLI tool rather tha
 - Live screencast streaming to Studio
 - Thread-scoped browser isolation
 
-For SDK-based browser automation, use [AgentBrowser](https://mastra.ai/docs/browser/agent-browser) or [Stagehand](https://mastra.ai/docs/browser/stagehand) instead.
+For SDK-based browser automation, use [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser) or [Stagehand](https://mastra.ai/integrations/browsers/stagehand) instead.
 
 ## Quickstart
 
@@ -145,7 +145,7 @@ CDP flag: `--ws` See [BrowserViewer reference](https://mastra.ai/reference/brows
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
-- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
+- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Workspace skills](https://mastra.ai/docs/workspace/skills)

package/.docs/{docs/browser → integrations/browsers}/firecrawl.md

@@ -2,7 +2,7 @@
 
 # Firecrawl
 
-The `@mastra/browser-firecrawl` package provides browser automation using the [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser). It provisions remote browser sessions through the Firecrawl API and drives them with the same deterministic, accessibility-first tools as [AgentBrowser](https://mastra.ai/docs/browser/agent-browser).
+The `@mastra/browser-firecrawl` package provides browser automation using the [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser). It provisions remote browser sessions through the Firecrawl API and drives them with the same deterministic, accessibility-first tools as [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser).
 
 `FirecrawlBrowser` extends `AgentBrowser`, so agents get the same toolset (`browser_goto`, `browser_snapshot`, `browser_click`, and so on) while the browser itself runs in Firecrawl's hosted infrastructure. No local Chromium install is needed.
 
@@ -124,6 +124,6 @@ const browser = new FirecrawlBrowser({
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [FirecrawlBrowser reference](https://mastra.ai/reference/browser/firecrawl-browser)

package/.docs/{docs/browser → integrations/browsers}/stagehand.md

@@ -167,6 +167,6 @@ This adds `browser_record` and `browser_record_caption` to the agent's toolset.
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser)

package/.docs/{docs/capabilities → integrations}/channels/discord.md

@@ -94,5 +94,5 @@ Use this URL anywhere the Discord adapter docs ask for the interactions endpoint
 
 ## Related
 
-- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
-- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)
+- [Channels overview](https://mastra.ai/docs/capabilities/channels)
+- [More](https://mastra.ai/docs/capabilities/channels)

package/.docs/integrations/channels/github.md

@@ -0,0 +1,103 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# GitHub
+
+The `@mastra/github-signals` provider lets an agent follow pull requests (PRs). It polls subscribed PRs and sends [notification signals](https://mastra.ai/docs/long-running-agents/signals) to the agent thread when relevant activity occurs.
+
+## Installation
+
+Install GitHub Signals and the memory packages used in this example:
+
+**npm**:
+
+```bash
+npm install @mastra/github-signals @mastra/libsql @mastra/memory
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/github-signals @mastra/libsql @mastra/memory
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/github-signals @mastra/libsql @mastra/memory
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/github-signals @mastra/libsql @mastra/memory
+```
+
+## Prerequisites
+
+GitHub Signals requires:
+
+- A Mastra storage adapter with memory and notification support. The provider stores each subscription in the thread's metadata, so the thread must already exist.
+- The `gitcrawl` command on `PATH`, configured to access the repositories you want to monitor. The provider runs `gitcrawl sync` and reads its SQLite database.
+- The `sqlite3` command on `PATH`.
+- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses `gh api` to check whether comment authors have access to the repository before notifying the agent.
+
+By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are also allowed. Configure `authorizedPermissions`, `authorizedBots`, or `ignoredBots` when you need different rules.
+
+## Agent and subscription
+
+Create one `GithubSignals` instance and register it on the agent. Register the agent and a storage adapter on the Mastra instance:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Mastra } from '@mastra/core/mastra'
+import { Memory } from '@mastra/memory'
+import { GithubSignals } from '@mastra/github-signals'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const githubSignals = new GithubSignals()
+
+export const devAgent = new Agent({
+  id: 'dev-agent',
+  name: 'Development Agent',
+  instructions: 'Triage pull request activity and help resolve issues.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory(),
+  signals: [githubSignals],
+})
+
+export const mastra = new Mastra({
+  agents: { devAgent },
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+})
+```
+
+After the agent has created a memory thread, subscribe that thread to a PR. Passing `owner` and `repo` works from any directory:
+
+```typescript
+await githubSignals.subscribeThreadToPR({
+  threadId: 'thread-123',
+  resourceId: 'user-123',
+  pr: {
+    owner: 'acme',
+    repo: 'web-app',
+    number: 42,
+  },
+})
+```
+
+The provider syncs the PR immediately, stores the subscription, and starts polling every five minutes. Set `pollIntervalMs` in the `GithubSignals` constructor to change the interval. If the process restarts, call `startPollingForThread()` for each persisted thread subscription to resume polling.
+
+## Pull request notifications
+
+GitHub Signals notifies the agent when a subscribed PR has:
+
+- A new authorized comment, commit, or other pull request activity.
+- A change in unresolved review threads.
+- Continuous integration (CI) checks that start, fail, or recover.
+- Merge conflicts that appear or are resolved.
+- A state change to closed, reopened, or merged.
+
+The initial sync sends a baseline notification with the current PR state. A merge automatically removes the thread's subscription to that PR.

package/.docs/{docs/capabilities → integrations}/channels/imessage.md

@@ -110,6 +110,10 @@ https://your-app.example.com/api/agents/imessage-agent/channels/imessage/webhook
 
 Register this URL in the [Photon dashboard](https://app.photon.codes), then set the signing secret it returns as `IMESSAGE_WEBHOOK_SECRET`. The secret is shown once at registration. The adapter verifies the signature on every delivery and rejects requests that don't match. Webhooks are available in hosted mode only.
 
+> **Note:** Photon delivers to public HTTPS endpoints only. It won't deliver to `http://`, to private addresses like `localhost`, or through a redirect. For local development, use a tunnel as described in the [Channels overview](https://mastra.ai/docs/capabilities/channels).
+
+## Duplicate deliveries
+
 Photon retries failed deliveries with backoff and delivers at least once, so the same message can arrive twice. Chat SDK drops the repeat using the channel state adapter, and Mastra's default keeps those dedup keys in memory. That covers a single long-running server.
 
 A repeat can still reach the agent after a restart, or on serverless where the retry is routed to a different instance. Pass a shared state adapter on `channels.state` so dedup keys are visible everywhere. Install one alongside the adapter:
@@ -157,7 +161,11 @@ channels: {
 
 This matters most for tools with side effects, where handling the same message twice is visible to the user.
 
-> **Note:** Photon delivers to public HTTPS endpoints only. It won't deliver to `http://`, to private addresses like `localhost`, or through a redirect. For local development, use a tunnel as described in the [Channels overview](https://mastra.ai/docs/capabilities/channels/overview).
+## Read receipts
+
+iPhone Messages sends a read receipt for every message the agent posts, and the adapter delivers those receipts as inbound messages with no text and no attachments. Mastra skips them, so the agent doesn't answer its own reply in a loop. Their message IDs carry a `:read:` suffix, and they show up as skipped messages at `debug` log level.
+
+The same rule applies to every adapter: an inbound message with neither text nor attachments never starts an agent run. A custom `onDirectMessage`, `onMention`, or `onSubscribedMessage` handler still receives it and can act on it before calling `defaultHandler`.
 
 ## Gateway listener
 
@@ -173,9 +181,9 @@ imessage: {
 },
 ```
 
-On serverless platforms, prefer webhooks. A gateway listener needs a process that stays alive. See [Serverless deployment](https://mastra.ai/docs/capabilities/channels/overview).
+On serverless platforms, prefer webhooks. A gateway listener needs a process that stays alive. See [Serverless deployment](https://mastra.ai/docs/capabilities/channels).
 
 ## Related
 
-- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
-- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)
+- [Channels overview](https://mastra.ai/docs/capabilities/channels)
+- [More](https://mastra.ai/docs/capabilities/channels)