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

package/.docs/reference/file-based-agents/studio.md

@@ -2,6 +2,8 @@
 
 # Studio
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra configures [Studio](https://mastra.ai/docs/studio/overview) from a `studio.ts` file directly under `src/mastra/`. The file default-exports a `StudioConfig` object for Studio authentication and authorization: who can access Studio, and what authenticated users can do.
 
 Use this page for the file-based convention. For auth providers, role-based access control (RBAC), and fine-grained authorization (FGA), see [Studio auth](https://mastra.ai/docs/studio/auth).
@@ -38,7 +40,7 @@ Studio opens without authentication in local development. Add `studio.ts` when y
 
 ## Add authentication
 
-Use an auth provider to require sign-in before users can access Studio. This example uses [WorkOS](https://mastra.ai/docs/server/auth/workos):
+Use an auth provider to require sign-in before users can access Studio. This example uses [WorkOS](https://mastra.ai/integrations/auth/workos):
 
 ```typescript
 import { MastraAuthWorkos } from '@mastra/auth-workos'

package/.docs/reference/file-based-agents/subagents.md

@@ -2,6 +2,8 @@
 
 # Subagents
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory and calls that tool to hand off a task. The subagent's result returns to the parent conversation.
 
 Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/capabilities/subagents).

package/.docs/reference/file-based-agents/tools.md

@@ -2,6 +2,8 @@
 
 # Tools
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent discovers tools from `.ts` and `.js` files directly under its `tools/` directory. Each discovered file is imported at build time, the file must default-export a [`createTool()`](https://mastra.ai/reference/tools/create-tool) result, and the filename without its extension becomes the tool key the model can call.
 
 Use this page for the file-based convention. For tool schemas, execution options, output shaping, and approval options, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool).

package/.docs/reference/file-based-agents/workflows.md

@@ -2,6 +2,8 @@
 
 # Workflows
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra discovers project-level workflows from `.ts` and `.js` files under `src/mastra/workflows/`. This convention isn't scoped to one agent: every file with a default export becomes a registered workflow, and the filename becomes the workflow key.
 
 Use this page for the file-based convention. For steps, schemas, control flow, streaming, state, and workflow execution, see [Workflows overview](https://mastra.ai/docs/workflows/overview).

package/.docs/reference/file-based-agents/workspace.md

@@ -2,6 +2,8 @@
 
 # Workspace
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they can read and write files and run shell commands without extra configuration.
 
 Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Workspaces](https://mastra.ai/docs/workspace/overview).

package/.docs/reference/index.md

@@ -212,6 +212,28 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listThreads()](https://mastra.ai/reference/memory/listThreads)
 - [.recall()](https://mastra.ai/reference/memory/recall)
 - [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
+- [AgentNetwork to .network()](https://mastra.ai/reference/migrations/agentnetwork)
+- [AI SDK v4 to v5](https://mastra.ai/reference/migrations/ai-sdk-v4-to-v5)
+- [Mastra Cloud to Mastra platform](https://mastra.ai/reference/migrations/mastra-cloud)
+- [VNext to Standard APIs](https://mastra.ai/reference/migrations/vnext-to-standard-apis)
+- [.network() to Supervisor Agents](https://mastra.ai/reference/migrations/network-to-supervisor)
+- [Overview](https://mastra.ai/reference/migrations/upgrade-to-v1/overview)
+- [Agents](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
+- [CLI](https://mastra.ai/reference/migrations/upgrade-to-v1/cli)
+- [Client SDK](https://mastra.ai/reference/migrations/upgrade-to-v1/client)
+- [Deployment](https://mastra.ai/reference/migrations/upgrade-to-v1/deployment)
+- [Evals](https://mastra.ai/reference/migrations/upgrade-to-v1/evals)
+- [Mastra](https://mastra.ai/reference/migrations/upgrade-to-v1/mastra)
+- [MCP](https://mastra.ai/reference/migrations/upgrade-to-v1/mcp)
+- [Memory](https://mastra.ai/reference/migrations/upgrade-to-v1/memory)
+- [Processors](https://mastra.ai/reference/migrations/upgrade-to-v1/processors)
+- [RAG](https://mastra.ai/reference/migrations/upgrade-to-v1/rag)
+- [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
+- [Tools](https://mastra.ai/reference/migrations/upgrade-to-v1/tools)
+- [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)
+- [Vectors](https://mastra.ai/reference/migrations/upgrade-to-v1/vectors)
+- [Voice](https://mastra.ai/reference/migrations/upgrade-to-v1/voice)
+- [Workflows](https://mastra.ai/reference/migrations/upgrade-to-v1/workflows)
 - [Feedback](https://mastra.ai/reference/observability/feedback)
 - [PinoLogger](https://mastra.ai/reference/logging/pino-logger)
 - [Automatic Metrics](https://mastra.ai/reference/observability/metrics/automatic-metrics)
@@ -248,14 +270,19 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PubSub](https://mastra.ai/reference/pubsub/base)
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams)
 - [UnixSocketPubSub](https://mastra.ai/reference/pubsub/unix-socket-pubsub)
+- [Overview](https://mastra.ai/reference/rag/overview)
+- [Chunking and Embedding](https://mastra.ai/reference/rag/chunking-and-embedding)
 - [DatabaseConfig](https://mastra.ai/reference/rag/database-config)
 - [Embed](https://mastra.ai/reference/rag/embeddings)
 - [ExtractParams](https://mastra.ai/reference/rag/extract-params)
 - [GraphRAG](https://mastra.ai/reference/rag/graph-rag)
+- [GraphRAG Guide](https://mastra.ai/reference/rag/graph-rag-guide)
 - [MDocument](https://mastra.ai/reference/rag/document)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
 - [rerank()](https://mastra.ai/reference/rag/rerank)
 - [rerankWithScorer()](https://mastra.ai/reference/rag/rerankWithScorer)
+- [Retrieval](https://mastra.ai/reference/rag/retrieval)
+- [Vector Databases](https://mastra.ai/reference/rag/vector-databases)
 - [.chunk()](https://mastra.ai/reference/rag/chunk)
 - [Overview](https://mastra.ai/reference/schedules/overview)
 - [createRoute()](https://mastra.ai/reference/server/create-route)
@@ -272,23 +299,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [TaskSignalProvider](https://mastra.ai/reference/signals/task-signal-provider)
 - [WebhookSignalProvider](https://mastra.ai/reference/signals/webhook-signal-provider)
 - [Overview](https://mastra.ai/reference/storage/overview)
-- [Aurora DSQL Storage](https://mastra.ai/reference/storage/dsql)
-- [ClickHouse Storage](https://mastra.ai/reference/storage/clickhouse)
-- [Cloudflare D1 Storage](https://mastra.ai/reference/storage/cloudflare-d1)
-- [Cloudflare KV Storage](https://mastra.ai/reference/storage/cloudflare)
 - [Composite Storage](https://mastra.ai/reference/storage/composite)
-- [Convex Storage](https://mastra.ai/reference/storage/convex)
-- [DuckDB Storage](https://mastra.ai/reference/storage/duckdb)
-- [DynamoDB Storage](https://mastra.ai/reference/storage/dynamodb)
-- [Google Cloud Spanner Storage](https://mastra.ai/reference/storage/spanner)
-- [LanceDB Storage](https://mastra.ai/reference/storage/lance)
-- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
-- [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
-- [MSSQL Storage](https://mastra.ai/reference/storage/mssql)
-- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
-- [Redis Storage](https://mastra.ai/reference/storage/redis)
 - [Retention (prune)](https://mastra.ai/reference/storage/retention)
-- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
 - [ChunkType](https://mastra.ai/reference/streaming/ChunkType)
 - [smoothStream()](https://mastra.ai/reference/streaming/smoothStream)
 - [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput)
@@ -301,7 +313,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [askUserTool](https://mastra.ai/reference/tools/ask-user-tool)
-- [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
 - [createBedrockKBTool()](https://mastra.ai/reference/tools/bedrock-kb-tool)
 - [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
@@ -311,10 +322,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [IsolatedVmCodeModeTransport](https://mastra.ai/reference/tools/isolated-vm-transport)
 - [MCPClient](https://mastra.ai/reference/tools/mcp-client)
 - [MCPServer](https://mastra.ai/reference/tools/mcp-server)
-- [Perplexity Tools](https://mastra.ai/reference/tools/perplexity)
+- [QuickJsCodeModeTransport](https://mastra.ai/reference/tools/quickjs-transport)
 - [submitPlanTool](https://mastra.ai/reference/tools/submit-plan-tool)
 - [Task tools](https://mastra.ai/reference/tools/task-tools)
-- [Tavily Tools](https://mastra.ai/reference/tools/tavily)
 - [Amazon S3 Vector Store](https://mastra.ai/reference/vectors/s3vectors)
 - [Astra Vector Store](https://mastra.ai/reference/vectors/astra)
 - [Chroma Vector Store](https://mastra.ai/reference/vectors/chroma)
@@ -327,32 +337,15 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Vector Store](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB Vector Store](https://mastra.ai/reference/vectors/mongodb)
 - [OpenSearch Vector Store](https://mastra.ai/reference/vectors/opensearch)
+- [OracleDB Vector Store](https://mastra.ai/reference/vectors/oracledb)
 - [PG Vector Store](https://mastra.ai/reference/vectors/pg)
 - [Pinecone Vector Store](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
 - [Turbopuffer Vector Store](https://mastra.ai/reference/vectors/turbopuffer)
 - [Upstash Vector Store](https://mastra.ai/reference/vectors/upstash)
-- [AWS Nova Sonic](https://mastra.ai/reference/voice/aws-nova-sonic)
-- [Azure](https://mastra.ai/reference/voice/azure)
-- [Cloudflare](https://mastra.ai/reference/voice/cloudflare)
 - [Composite Voice](https://mastra.ai/reference/voice/composite-voice)
-- [Deepgram](https://mastra.ai/reference/voice/deepgram)
-- [ElevenLabs](https://mastra.ai/reference/voice/elevenlabs)
 - [Events](https://mastra.ai/reference/voice/voice.events)
-- [Google](https://mastra.ai/reference/voice/google)
-- [Google Gemini Live](https://mastra.ai/reference/voice/google-gemini-live)
-- [Inworld](https://mastra.ai/reference/voice/inworld)
-- [Inworld Realtime](https://mastra.ai/reference/voice/inworld-realtime)
-- [LiveKit](https://mastra.ai/reference/voice/livekit)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
-- [Mistral](https://mastra.ai/reference/voice/mistral)
-- [Murf](https://mastra.ai/reference/voice/murf)
-- [OpenAI](https://mastra.ai/reference/voice/openai)
-- [OpenAI Realtime](https://mastra.ai/reference/voice/openai-realtime)
-- [PlayAI](https://mastra.ai/reference/voice/playai)
-- [Sarvam](https://mastra.ai/reference/voice/sarvam)
-- [Speechify](https://mastra.ai/reference/voice/speechify)
-- [xAI Realtime](https://mastra.ai/reference/voice/xai-realtime)
 - [.addInstructions()](https://mastra.ai/reference/voice/voice.addInstructions)
 - [.addTools()](https://mastra.ai/reference/voice/voice.addTools)
 - [.answer()](https://mastra.ai/reference/voice/voice.answer)
@@ -390,29 +383,11 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.start()](https://mastra.ai/reference/workflows/run-methods/start)
 - [.startAsync()](https://mastra.ai/reference/workflows/run-methods/startAsync)
 - [.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
-- [AgentCoreRuntimeSandbox](https://mastra.ai/reference/workspace/agentcore-runtime-sandbox)
-- [AgentFSFilesystem](https://mastra.ai/reference/workspace/agentfs-filesystem)
-- [AppleContainerSandbox](https://mastra.ai/reference/workspace/apple-container-sandbox)
-- [ArchilFilesystem](https://mastra.ai/reference/workspace/archil-filesystem)
-- [AzureBlobFilesystem](https://mastra.ai/reference/workspace/azure-blob-filesystem)
-- [BlaxelSandbox](https://mastra.ai/reference/workspace/blaxel-sandbox)
-- [DaytonaSandbox](https://mastra.ai/reference/workspace/daytona-sandbox)
-- [DockerSandbox](https://mastra.ai/reference/workspace/docker-sandbox)
-- [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox)
-- [FilesSDKFilesystem](https://mastra.ai/reference/workspace/files-sdk-filesystem)
-- [GCSFilesystem](https://mastra.ai/reference/workspace/gcs-filesystem)
-- [GoogleDriveFilesystem](https://mastra.ai/reference/workspace/google-drive-filesystem)
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
-- [MesaFilesystem](https://mastra.ai/reference/workspace/mesa-filesystem)
-- [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
 - [PlatformFilesystem](https://mastra.ai/reference/workspace/platform-filesystem)
 - [PlatformSandbox](https://mastra.ai/reference/workspace/platform-sandbox)
-- [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
-- [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
 - [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)
-- [VercelSandbox](https://mastra.ai/reference/workspace/vercel-sandbox)
-- [VercelServerlessSandbox](https://mastra.ai/reference/workspace/vercel-serverless)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
 - [WorkspaceFilesystem](https://mastra.ai/reference/workspace/filesystem)
 - [WorkspaceSandbox](https://mastra.ai/reference/workspace/sandbox)

package/.docs/{guides/getting-started → reference}/manual-install.md

@@ -108,7 +108,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    }
    ```
 
-   > **Info:** Mastra requires modern `module` and `moduleResolution` settings. Using `CommonJS` or `node` will cause resolution errors.
+   > **Note:** Mastra requires modern `module` and `moduleResolution` settings. Using `CommonJS` or `node` will cause resolution errors.
 
 3. Create an `.env` file:
 
@@ -157,7 +157,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    })
    ```
 
-   > **Info:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/using-tools).
+   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/using-tools).
 
 5. Create a `weather-agent.ts` file:
 

package/.docs/{guides → reference}/migrations/ai-sdk-v4-to-v5.md

@@ -2,7 +2,7 @@
 
 # Migrate from AI SDK v4 to v5
 
-Looking for integration docs? See [Using AI SDK](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
+Looking for integration docs? See [Using AI SDK](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui).
 
 Follow the official [AI SDK v5 Migration Guide](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0) for all AI SDK core breaking changes, package updates, and API changes.
 

package/.docs/{guides → reference}/migrations/mastra-cloud.md

@@ -95,7 +95,7 @@ If you prefer to work from the command line, or need to script the export, you c
 
    > **Note:** These variables only appear for projects that were provisioned with Cloud Store. If you brought your own database to Mastra Cloud, you already have these credentials and can skip ahead to [Point your Mastra app at the new database](#point-your-mastra-app-at-the-new-database).
 
-   > **Info:** If the variables are missing, the values do not decrypt, or the Turso CLI rejects the token, email <support@mastra.ai> from the address associated with your Mastra Cloud account and ask for the libSQL URL and auth token for the project you want to export. Include the project name/ID. Support can also run the dump on your behalf if CLI access is blocked on your network.
+   > **Note:** If the variables are missing, the values do not decrypt, or the Turso CLI rejects the token, email <support@mastra.ai> from the address associated with your Mastra Cloud account and ask for the libSQL URL and auth token for the project you want to export. Include the project name/ID. Support can also run the dump on your behalf if CLI access is blocked on your network.
 
 2. Install the Turso CLI.
 
@@ -179,7 +179,7 @@ export const mastra = new Mastra({
 })
 ```
 
-See the [libSQL storage reference](https://mastra.ai/reference/storage/libsql) for the full set of options.
+See the [libSQL storage reference](https://mastra.ai/integrations/databases/libsql) for the full set of options.
 
 ### Verify the migration
 

package/.docs/{guides → reference}/migrations/upgrade-to-v1/cli.md

@@ -16,7 +16,7 @@ npx mastra migrate
 
 The command bundles your project and connects to your configured storage before running any necessary migrations. It currently supports migrating duplicate span entries that may prevent unique constraint creation.
 
-See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details on when this migration is needed.
+See the [Storage migration guide](https://mastra.ai/reference/migrations/upgrade-to-v1/storage) for details on when this migration is needed.
 
 ## Removed
 

package/.docs/{guides → reference}/migrations/upgrade-to-v1/memory.md

@@ -283,6 +283,6 @@ To migrate, move processor configuration from Memory to Agent using `inputProces
   });
 ```
 
-Additionally, the `@mastra/memory/processors` import path has been removed. Import processors from `@mastra/core/processors` instead. See the [processors migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/processors) for details.
+Additionally, the `@mastra/memory/processors` import path has been removed. Import processors from `@mastra/core/processors` instead. See the [processors migration guide](https://mastra.ai/reference/migrations/upgrade-to-v1/processors) for details.
 
 For more information on using processors with agents, see the [Processors docs](https://mastra.ai/docs/agents/processors). For a complete example with memory, see the [TokenLimiter reference](https://mastra.ai/reference/processors/token-limiter-processor).

package/.docs/{guides → reference}/migrations/upgrade-to-v1/overview.md

@@ -12,7 +12,7 @@ This guide covers the breaking changes when upgrading from Mastra 0.x to v1.0. T
 
 > **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens don't work with Mastra platform. Create new ones with `mastra auth tokens create`.
 >
-> If you upgrade to v1 packages without also migrating your `telemetry:` config to `observability:` and creating a Studio project, observability data will stop flowing. Follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) end to end.
+> If you upgrade to v1 packages without also migrating your `telemetry:` config to `observability:` and creating a Studio project, observability data will stop flowing. Follow the [Mastra Cloud migration guide](https://mastra.ai/reference/migrations/mastra-cloud) end to end.
 
 ## Migration strategy
 
@@ -62,25 +62,25 @@ Work through the [migration checklist](#migration-checklist) below to update you
 > npx @mastra/codemod@latest v1
 > ```
 
-> **Database Migration Required:** If you're using PostgreSQL or LibSQL storage, you'll need to run a database migration. See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details.
+> **Database Migration Required:** If you're using PostgreSQL or LibSQL storage, you'll need to run a database migration. See the [Storage migration guide](https://mastra.ai/reference/migrations/upgrade-to-v1/storage) for details.
 
 ## Breaking changes by area
 
-- **[Mastra Class](https://mastra.ai/guides/migrations/upgrade-to-v1/mastra)** - Import restructuring and property access changes.
-- **[Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)** - Voice methods moved to namespace and streaming API updates.
-- **[Tools](https://mastra.ai/guides/migrations/upgrade-to-v1/tools)** - CreateTool execute signature changed to separate input and context.
-- **[Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)** - Function name changes and legacy features removed.
-- **[Memory](https://mastra.ai/guides/migrations/upgrade-to-v1/memory)** - Configuration now requires explicit parameters and defaults changed.
-- **[Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)** - Pagination standardized and methods renamed to list pattern.
-- **[Vectors](https://mastra.ai/guides/migrations/upgrade-to-v1/vectors)** - Vector store methods renamed to list pattern.
-- **[RAG](https://mastra.ai/guides/migrations/upgrade-to-v1/rag)** - Parameter naming updated for clarity.
-- **[MCP](https://mastra.ai/guides/migrations/upgrade-to-v1/mcp)** - Tool context reorganized and deprecated client classes removed.
-- **[Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)** - OTEL telemetry replaced with dedicated observability package and exporters.
-- **[Evals & Scorers](https://mastra.ai/guides/migrations/upgrade-to-v1/evals)** - Scorers API consolidated with new naming conventions.
-- **[CLI](https://mastra.ai/guides/migrations/upgrade-to-v1/cli)** - Commands and flags removed for simpler interface.
-- **[Deployment](https://mastra.ai/guides/migrations/upgrade-to-v1/deployment)** - CloudflareDeployer configuration updated to use standard wrangler.json property names.
-- **[Client SDKs](https://mastra.ai/guides/migrations/upgrade-to-v1/client)** - Types and utilities renamed for consistency.
-- **[Voice Packages](https://mastra.ai/guides/migrations/upgrade-to-v1/voice)** - Packages renamed from speech to voice.
+- **[Mastra Class](https://mastra.ai/reference/migrations/upgrade-to-v1/mastra)** - Import restructuring and property access changes.
+- **[Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)** - Voice methods moved to namespace and streaming API updates.
+- **[Tools](https://mastra.ai/reference/migrations/upgrade-to-v1/tools)** - CreateTool execute signature changed to separate input and context.
+- **[Workflows](https://mastra.ai/reference/migrations/upgrade-to-v1/workflows)** - Function name changes and legacy features removed.
+- **[Memory](https://mastra.ai/reference/migrations/upgrade-to-v1/memory)** - Configuration now requires explicit parameters and defaults changed.
+- **[Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)** - Pagination standardized and methods renamed to list pattern.
+- **[Vectors](https://mastra.ai/reference/migrations/upgrade-to-v1/vectors)** - Vector store methods renamed to list pattern.
+- **[RAG](https://mastra.ai/reference/migrations/upgrade-to-v1/rag)** - Parameter naming updated for clarity.
+- **[MCP](https://mastra.ai/reference/migrations/upgrade-to-v1/mcp)** - Tool context reorganized and deprecated client classes removed.
+- **[Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)** - OTEL telemetry replaced with dedicated observability package and exporters.
+- **[Evals & Scorers](https://mastra.ai/reference/migrations/upgrade-to-v1/evals)** - Scorers API consolidated with new naming conventions.
+- **[CLI](https://mastra.ai/reference/migrations/upgrade-to-v1/cli)** - Commands and flags removed for simpler interface.
+- **[Deployment](https://mastra.ai/reference/migrations/upgrade-to-v1/deployment)** - CloudflareDeployer configuration updated to use standard wrangler.json property names.
+- **[Client SDKs](https://mastra.ai/reference/migrations/upgrade-to-v1/client)** - Types and utilities renamed for consistency.
+- **[Voice Packages](https://mastra.ai/reference/migrations/upgrade-to-v1/voice)** - Packages renamed from speech to voice.
 
 ## Migration checklist
 
@@ -96,30 +96,30 @@ Work through this checklist in order, starting with high-impact changes that aff
 
 ### High Impact Changes
 
-- Update `createTool` tool signatures to `(inputData, context)` format - [Tools](https://mastra.ai/guides/migrations/upgrade-to-v1/tools)
-- Restructure `@mastra/core` imports to use subpath imports - [Mastra Class](https://mastra.ai/guides/migrations/upgrade-to-v1/mastra)
-- Update pagination from `offset/limit` to `page/perPage` - [Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)
-- Install `@mastra/observability` and wrap configuration with `new Observability()` - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)
-- Migrate from `telemetry:` to `observability:` configuration (if upgrading from 0.x OTEL) - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)
+- Update `createTool` tool signatures to `(inputData, context)` format - [Tools](https://mastra.ai/reference/migrations/upgrade-to-v1/tools)
+- Restructure `@mastra/core` imports to use subpath imports - [Mastra Class](https://mastra.ai/reference/migrations/upgrade-to-v1/mastra)
+- Update pagination from `offset/limit` to `page/perPage` - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
+- Install `@mastra/observability` and wrap configuration with `new Observability()` - [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)
+- Migrate from `telemetry:` to `observability:` configuration (if upgrading from 0.x OTEL) - [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)
 
 ### Medium Impact Changes
 
-- Rename `RuntimeContext` to `RequestContext` throughout codebase - [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent), [Tools](https://mastra.ai/guides/migrations/upgrade-to-v1/tools), [Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)
-- Update storage methods from `get*` to `list*` pattern - [Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)
-- Replace direct property access with getter methods - [Mastra Class](https://mastra.ai/guides/migrations/upgrade-to-v1/mastra), [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)
-- Update memory scope if relying on default `thread` scope - [Memory](https://mastra.ai/guides/migrations/upgrade-to-v1/memory)
-- Update vector store calls to use named arguments - [Storage](https://mastra.ai/guides/migrations/upgrade-to-v1/storage)
-- Remove `format` parameter from agent methods - [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)
-- Update voice methods to use `agent.voice` namespace - [Agent Class](https://mastra.ai/guides/migrations/upgrade-to-v1/agent)
-- Rename configuration property `processors` to `spanOutputProcessors` (if using custom processors) - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)
-
-### Low Impact Changes
-
-- Rename `keepSeparator` to `separatorPosition` in chunk options - [RAG](https://mastra.ai/guides/migrations/upgrade-to-v1/rag)
-- Rename `createRunAsync` to `createRun` - [Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)
-- Update voice package names from `@mastra/speech-*` to `@mastra/voice-*` - [Voice Packages](https://mastra.ai/guides/migrations/upgrade-to-v1/voice)
-- Update scorer methods: `runExperiment` → `runEvals`, `getScorerByName` → `getScorerById` - [Evals & Scorers](https://mastra.ai/guides/migrations/upgrade-to-v1/evals)
-- Remove deprecated CLI flags - [CLI](https://mastra.ai/guides/migrations/upgrade-to-v1/cli)
-- Update client SDK types from `Get*` to `List*` - [Client SDKs](https://mastra.ai/guides/migrations/upgrade-to-v1/client)
-- Replace `runCount` with `retryCount` - [Workflows](https://mastra.ai/guides/migrations/upgrade-to-v1/workflows)
-- Update custom exporter method `exportEvent` to `exportTracingEvent` (if using custom exporters) - [Tracing](https://mastra.ai/guides/migrations/upgrade-to-v1/tracing)
+- Rename `RuntimeContext` to `RequestContext` throughout codebase - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent), [Tools](https://mastra.ai/reference/migrations/upgrade-to-v1/tools), [Workflows](https://mastra.ai/reference/migrations/upgrade-to-v1/workflows)
+- Update storage methods from `get*` to `list*` pattern - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
+- Replace direct property access with getter methods - [Mastra Class](https://mastra.ai/reference/migrations/upgrade-to-v1/mastra), [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
+- Update memory scope if relying on default `thread` scope - [Memory](https://mastra.ai/reference/migrations/upgrade-to-v1/memory)
+- Update vector store calls to use named arguments - [Storage](https://mastra.ai/reference/migrations/upgrade-to-v1/storage)
+- Remove `format` parameter from agent methods - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
+- Update voice methods to use `agent.voice` namespace - [Agent Class](https://mastra.ai/reference/migrations/upgrade-to-v1/agent)
+- Rename configuration property `processors` to `spanOutputProcessors` (if using custom processors) - [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)
+
+### Low-Impact Changes
+
+- Rename `keepSeparator` to `separatorPosition` in chunk options - [RAG](https://mastra.ai/reference/migrations/upgrade-to-v1/rag)
+- Rename `createRunAsync` to `createRun` - [Workflows](https://mastra.ai/reference/migrations/upgrade-to-v1/workflows)
+- Update voice package names from `@mastra/speech-*` to `@mastra/voice-*` - [Voice Packages](https://mastra.ai/reference/migrations/upgrade-to-v1/voice)
+- Update scorer methods: `runExperiment` → `runEvals`, `getScorerByName` → `getScorerById` - [Evals & Scorers](https://mastra.ai/reference/migrations/upgrade-to-v1/evals)
+- Remove deprecated CLI flags - [CLI](https://mastra.ai/reference/migrations/upgrade-to-v1/cli)
+- Update client SDK types from `Get*` to `List*` - [Client SDKs](https://mastra.ai/reference/migrations/upgrade-to-v1/client)
+- Replace `runCount` with `retryCount` - [Workflows](https://mastra.ai/reference/migrations/upgrade-to-v1/workflows)
+- Update custom exporter method `exportEvent` to `exportTracingEvent` (if using custom exporters) - [Tracing](https://mastra.ai/reference/migrations/upgrade-to-v1/tracing)

package/.docs/{guides → reference}/migrations/upgrade-to-v1/tools.md

@@ -84,7 +84,7 @@ The `suspendPayload` gets validated against the `suspendSchema` when the tool is
 
 To skip the `suspendSchema` or `resumeSchema` validation, don't define `suspendSchema` or `resumeSchema` in the tool creation.
 
-> **Note:** For MCP-specific tool context changes, see the [MCP migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/mcp).
+> **Note:** For MCP-specific tool context changes, see the [MCP migration guide](https://mastra.ai/reference/migrations/upgrade-to-v1/mcp).
 
 ### `RuntimeContext` to `RequestContext`
 

package/.docs/{guides → reference}/migrations/upgrade-to-v1/tracing.md

@@ -6,7 +6,7 @@ The observability system has been restructured in v1 with a dedicated `@mastra/o
 
 > **Observability data stops flowing on upgrade:** If you upgrade Mastra packages to v1 without migrating your `telemetry:` config to `observability:`, the old config is ignored at runtime. Your service will start cleanly with no error, but **no traces, logs, or metrics will be sent anywhere**. If you were sending data to Mastra Cloud, the dashboard will go empty.
 >
-> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud). The new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
+> Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/reference/migrations/mastra-cloud). The new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
 
 > **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes remain available from `@mastra/observability` and behave identically, but they're deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`. Existing imports of `CloudExporter` or `DefaultExporter` continue to work until they're removed in a future major version.
 
@@ -354,14 +354,14 @@ No separate instrumentation files or special startup flags required.
 
 If you were using OTEL-based telemetry with specific providers in 0.x, here's how to configure them in v1:
 
-| Provider                                                  | Exporter          | Guide                                                                           | Reference                                                                           |
-| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/docs/observability/integrations/exporters/arize)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
-| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/docs/observability/integrations/exporters/braintrust) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
-| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/docs/observability/integrations/exporters/langfuse)   | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
-| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/docs/observability/integrations/exporters/langsmith)  | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
-| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/docs/observability/integrations/exporters/otel)       | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
-| LangWatch                                                 | \<coming soon>    | -                                                                               | -                                                                                   |
+| Provider                                                  | Exporter          | Guide                                                               | Reference                                                                           |
+| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/integrations/observability/arize)         | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
+| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/integrations/observability/braintrust)    | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
+| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/integrations/observability/langfuse)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
+| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/integrations/observability/langsmith)     | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
+| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/integrations/observability/opentelemetry) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
+| LangWatch                                                 | \<coming soon>    | -                                                                   | -                                                                                   |
 
 ### Installation
 
@@ -417,4 +417,4 @@ yarn add @mastra/otel-exporter@latest
 bun add @mastra/otel-exporter@latest
 ```
 
-Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/docs/observability/integrations/exporters/otel)).
+Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/integrations/observability/opentelemetry)).

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -157,7 +157,7 @@ const mastra = new Mastra({
 
 The DatadogBridge requires `dd-trace` to be initialized before any other imports so its auto-instrumentation can patch HTTP, database, and framework libraries at load time.
 
-See the [DatadogBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.
+See the [DatadogBridge Guide](https://mastra.ai/integrations/observability/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.
 
 ## Span mapping
 
@@ -208,6 +208,6 @@ The bridge reads configuration from these environment variables:
 
 ## Related
 
-- [DatadogBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/datadog) - Setup guide with examples
+- [DatadogBridge Guide](https://mastra.ai/integrations/observability/datadog) - Setup guide with examples
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts
 - [DatadogExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/datadog) - LLM Observability only, no `dd-trace` APM

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -120,7 +120,7 @@ const mastra = new Mastra({
 
 The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
 
-See the [OtelBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
+See the [OtelBridge Guide](https://mastra.ai/integrations/observability/opentelemetry) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
 
 ## Tags support
 
@@ -150,6 +150,6 @@ This format ensures compatibility with all OTEL-compatible backends and collecto
 
 ## Related
 
-- [OtelBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/otel): Setup guide with examples
+- [OtelBridge Guide](https://mastra.ai/integrations/observability/opentelemetry): Setup guide with examples
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts
 - [OtelExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel): OTEL exporter for sending traces

package/.docs/reference/observability/tracing/exporters/arize.md

@@ -138,6 +138,6 @@ Tags are stored using the OpenInference `tag.tags` attribute:
 
 ## Related
 
-- [ArizeExporter Documentation](https://mastra.ai/docs/observability/integrations/exporters/arize)
+- [ArizeExporter Documentation](https://mastra.ai/integrations/observability/arize)
 - [Phoenix Documentation](https://docs.arize.com/phoenix)
 - [Arize AX Documentation](https://docs.arize.com/)

package/.docs/reference/observability/tracing/exporters/arthur.md

@@ -119,6 +119,6 @@ Tags are stored using the OpenInference `tag.tags` attribute:
 
 ## Related
 
-- [ArthurExporter Documentation](https://mastra.ai/docs/observability/integrations/exporters/arthur)
+- [ArthurExporter Documentation](https://mastra.ai/integrations/observability/arthur)
 - [Arthur Engine documentation](https://docs.arthur.ai/)
 - [Arthur Engine repository](https://github.com/arthur-ai/arthur-engine)

package/.docs/reference/observability/tracing/exporters/confident-ai.md

@@ -4,7 +4,7 @@
 
 Sends Tracing data to [Confident AI](https://www.confident-ai.com/) for evaluation and observability. Exported by `@mastra/deepeval`, which builds on the DeepEval SDK.
 
-See [Confident AI exporter](https://mastra.ai/docs/observability/integrations/exporters/confident-ai) for setup and usage.
+See [Confident AI exporter](https://mastra.ai/integrations/observability/confident-ai) for setup and usage.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/datadog.md

@@ -4,7 +4,7 @@
 
 Sends Tracing data to Datadog's LLM Observability product for monitoring and analytics.
 
-> **Info:** If you also use `dd-trace` APM auto-instrumentation and need it correctly parented under Mastra spans, use the [DatadogBridge](https://mastra.ai/reference/observability/tracing/bridges/datadog) instead. The exporter sends LLM Observability data after execution completes, so it doesn't participate in `dd-trace`'s live scope.
+> **Note:** If you also use `dd-trace` APM auto-instrumentation and need it correctly parented under Mastra spans, use the [DatadogBridge](https://mastra.ai/reference/observability/tracing/bridges/datadog) instead. The exporter sends LLM Observability data after execution completes, so it doesn't participate in `dd-trace`'s live scope.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -177,6 +177,18 @@ The exporter batches tracing spans, logs, metrics, scores, and feedback for effi
 
 Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `id` prefix. The deprecated `CloudExporter` continues to emit `CLOUD_EXPORTER_*` `id`s.
 
+### Quota pause
+
+When an organization has exhausted its observability quota, the Mastra platform rejects publish requests with `402 Payment Required` plus the `x-mastra-observability: disabled` header. When the exporter sees a `402` (or the header) on any publish route, it:
+
+- Drops the rejected batch without retrying it
+- Pauses all five signal types (traces, logs, metrics, scores, feedback) and drops buffered and new events instead of sending them
+- Logs a warning that telemetry is paused
+- Probes the platform periodically with an empty batch, using the interval from the `x-mastra-observability-retry-after` header (seconds), or every 5 minutes if the header is absent
+- Resumes exporting automatically and logs a warning once the platform stops rejecting with `402`
+
+The probe timer doesn't keep the Node.js process alive, so short-lived and serverless processes exit normally while paused.
+
 ### Endpoint routing
 
 - Base origins derive signal endpoints automatically

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -200,6 +200,6 @@ Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute
 
 ## Related
 
-- [OtelExporter Guide](https://mastra.ai/docs/observability/integrations/exporters/otel): Setup guide with provider configurations
-- [OtelBridge](https://mastra.ai/docs/observability/integrations/bridges/otel): For bidirectional OTEL context integration
+- [OtelExporter Guide](https://mastra.ai/integrations/observability/opentelemetry): Setup guide with provider configurations
+- [OtelBridge](https://mastra.ai/integrations/observability/opentelemetry): For bidirectional OTEL context integration
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts

package/.docs/reference/processors/pii-detector.md

@@ -42,6 +42,8 @@ const processor = new PIIDetector({
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
+**options.onDetection** (`(event: PIIDetectionEvent) => void | Promise<void>`): Called whenever a detection result is produced, with detectionResult, the analyzed input, whether it was flagged, and the strategyApplied (the configured strategy when flagged, otherwise none). Fires for every analyzed message in processInput and processOutputResult, and for every LLM buffer flush during streaming; the streaming regex pass only reports when PII is found. Errors thrown by the callback are logged and ignored
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'pii-detector'

package/.docs/reference/processors/prompt-injection-detector.md

@@ -38,6 +38,8 @@ const processor = new PromptInjectionDetector({
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
+**options.onDetection** (`(event: PromptInjectionDetectionEvent) => void | Promise<void>`): Called for every analyzed message with detectionResult, the analyzed input, whether it was flagged, and the strategyApplied (the configured strategy when flagged, otherwise none). Use it to emit custom metrics. Errors thrown by the callback are logged and ignored
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'prompt-injection-detector'