@mastra/mcp-docs-server 1.2.17-alpha.13 → 1.2.17-alpha.16

package/.docs/course/02-agent-tools-mcp/32-conclusion.md

@@ -14,4 +14,4 @@ The power of MCP lies in its ability to connect your agent to a wide variety of
 
 As you continue to develop your Mastra agent, consider exploring other MCP servers and tools that might be useful for your specific use case. The Mastra ecosystem is constantly growing, with new tools and capabilities being added regularly.
 
-For more information on MCP and available servers, check out the [Mastra MCP documentation](https://mastra.ai/docs/mcp/overview).
+For more information on MCP and available servers, check out the [Mastra MCP documentation](https://mastra.ai/docs/connections/mcp).

package/.docs/docs/agents/code-mode.md

@@ -29,7 +29,7 @@ Each turn adds the full tool response to the agent's context window which can le
 
 With code mode, your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, and the function can reduce or aggregate results before returning one response to the agent.
 
-The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/sandbox). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
+The function runs in a [Workspace sandbox](https://mastra.ai/docs/sandbox/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
 
 Transports that bring their own execution boundary are the exception: with [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport) the program runs in an in-process V8 isolate and no sandbox is needed (see [In-process isolation](#in-process-isolation)).
 
@@ -183,5 +183,5 @@ See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport)
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
 - [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
-- [Tools](https://mastra.ai/docs/agents/using-tools)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Tools](https://mastra.ai/docs/agents/tools)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

package/.docs/docs/agents/guardrails.md

@@ -130,7 +130,7 @@ const scrubbedAgent = new Agent({
 
 Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
 
-> **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/mastra-server) for details.
+> **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/overview) for details.
 
 ## Hybrid processors
 

package/.docs/docs/agents/{agent-approval.md → human-in-the-loop.md}

@@ -48,7 +48,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Note:** Human-in-the-loop uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
+> **Note:** Human-in-the-loop uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage) on your Mastra instance or you'll see a "snapshot not found" error.
 >
 > Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.
 
@@ -510,11 +510,11 @@ Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `
 
 The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
 
-> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/storage/overview). The default in-memory store loses snapshots when the process exits.
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/storage). The default in-memory store loses snapshots when the process exits.
 
 ## Tool approval: Supervisor agents
 
-A [supervisor agent](https://mastra.ai/docs/capabilities/subagents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
+A [supervisor agent](https://mastra.ai/docs/subagents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
 
 1. The supervisor delegates a task to a subagent.
 2. The subagent calls a tool that has `requireApproval: true` or uses `suspend()`.
@@ -673,8 +673,8 @@ if (output.finishReason === 'suspended') {
 
 ## Related
 
-- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Tools](https://mastra.ai/docs/agents/tools)
 - [Agent overview](https://mastra.ai/docs/agents/overview)
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [Memory](https://mastra.ai/docs/memory/overview)
 - [Request context](https://mastra.ai/docs/server/request-context)

package/.docs/docs/agents/networks.md

@@ -2,7 +2,7 @@
 
 # Agent networks
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
 > See the [migration guide](https://mastra.ai/reference/migrations/network-to-supervisor) to upgrade.
 
@@ -95,7 +95,7 @@ console.log(final?.summary)
 
 When a primitive requires approval, the stream emits an `agent-execution-approval` or `tool-execution-approval` chunk. Use `approveNetworkToolCall()` or `declineNetworkToolCall()` to respond.
 
-Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/storage/overview) is enabled in your Mastra instance.
+Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/storage) is enabled in your Mastra instance.
 
 ```typescript
 const stream = await routingAgent.network('Perform some sensitive action', {
@@ -180,5 +180,5 @@ Requirements for automatic resumption:
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
+- [Supervisor agents](https://mastra.ai/docs/subagents)
 - [Migration: `.network()` to supervisor agents](https://mastra.ai/reference/migrations/network-to-supervisor)

package/.docs/docs/agents/overview.md

@@ -165,7 +165,7 @@ Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more i
 
 ## Use your agent
 
-After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/using-tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. See [Integrations](https://mastra.ai/integrations) to use agents in your application framework.
+After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. See [Integrations](https://mastra.ai/integrations) to use agents in your application framework.
 
 When referencing an agent from your Mastra instance, use `mastra.getAgentById()` to ensure it has access to shared services such as instance-level storage, logging, and agent registry. A directly imported agent can still work with its own local configuration, but it won't have access to those shared services.
 
@@ -202,18 +202,18 @@ Once your agent is running, use this table to find the right page for what you w
 
 | Goal                                                           | Start here                                                             |
 | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Give your agent tools to call external APIs or services        | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
+| Give your agent tools to call external APIs or services        | [Tools](https://mastra.ai/docs/agents/tools)                           |
 | Keep context and preferences across conversations              | [Memory](https://mastra.ai/docs/memory/overview)                       |
 | Get typed objects back instead of plain text                   | [Structured output](https://mastra.ai/docs/agents/structured-output)   |
-| Human-in-the-loop: Pause execution and wait for human approval | [Human-in-the-loop](https://mastra.ai/docs/agents/agent-approval)      |
-| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)     |
-| Register subagents                                             | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
+| Human-in-the-loop: Pause execution and wait for human approval | [Human-in-the-loop](https://mastra.ai/docs/agents/human-in-the-loop)   |
+| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/subagents)                  |
+| Register subagents                                             | [Tools](https://mastra.ai/docs/agents/tools)                           |
 | Intercept or transform messages before and after generation    | [Processors](https://mastra.ai/docs/agents/processors)                 |
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
-| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/capabilities/subagents)         |
+| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/subagents)                      |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
 | Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/reference/voice/overview)                    |
-| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels)               |
+| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/channels)                            |
 
 ## Multi-agent systems
 

package/.docs/docs/agents/processors.md

@@ -398,7 +398,7 @@ See the [`TokenLimiterProcessor` reference](https://mastra.ai/reference/processo
 
 Removes tool calls and results from messages sent to the LLM, saving tokens on verbose tool interactions. Optionally exclude only specific tools. This filter only affects the LLM input, filtered messages are still saved to memory.
 
-By default, `ToolCallFilter` filters the initial input before the agent loop starts. Use `filterAfterToolSteps` to also filter during each loop step while preserving recent tool-producing steps.
+By default, `ToolCallFilter` filters tool calls from prior history and leaves tool calls made during the current agent loop in place. Use `filterAfterToolSteps` to also filter during the loop while preserving the most recent tool-producing steps.
 
 ```typescript
 new ToolCallFilter({
@@ -640,7 +640,7 @@ Do not mention the reminder to the user or quote the tags back to them.`,
 await agent.generate('Your prompt', { maxSteps: MAX_STEPS })
 ```
 
-> **Note:** Reactive signals default to `tagName: 'system-reminder'`. Visit [Signals](https://mastra.ai/docs/long-running-agents/signals) for more on processor-emitted signals.
+> **Note:** Reactive signals default to `tagName: 'system-reminder'`. Visit [Signals](https://mastra.ai/docs/harness/signals) for more on processor-emitted signals.
 
 ### Deliver a reminder without retaining it
 

package/.docs/docs/agents/{using-tools.md → tools.md}

@@ -2,7 +2,7 @@
 
 # Tools
 
-Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
+Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/connections/mcp) to expand an agent's capabilities.
 
 **For AI agents:** Run `npx mastra api tool execute weather-tool '{"location":"San Francisco"}'` to test this tool directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api tool execute --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
 
@@ -166,7 +166,7 @@ export const weatherAgent = new Agent({
 
 ## Agents as tools
 
-Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/capabilities/subagents). Mastra converts each subagent to an `agent-<key>` tool. Include a `description` on each subagent so the supervisor knows when to delegate.
+Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/subagents). Mastra converts each subagent to an `agent-<key>` tool. Include a `description` on each subagent so the supervisor knows when to delegate.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -605,7 +605,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-`askUserTool` supports free-text, single-select (`options` array), and multi-select (`selectionMode: 'multi_select'`) prompts. Pair it with `autoResumeSuspendedTools` so the agent resumes automatically from the user's next chat message. See [Automatic tool resumption](https://mastra.ai/docs/agents/agent-approval) for details.
+`askUserTool` supports free-text, single-select (`options` array), and multi-select (`selectionMode: 'multi_select'`) prompts. Pair it with `autoResumeSuspendedTools` so the agent resumes automatically from the user's next chat message. See [Automatic tool resumption](https://mastra.ai/docs/agents/human-in-the-loop) for details.
 
 ### Submit a plan for review
 
@@ -643,7 +643,7 @@ const agent = new Agent({
 })
 ```
 
-Only one task can be `in_progress` at a time. The list is stored in the thread-scoped `threadState` storage domain and projected onto the agent's [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane, so it survives observational-memory truncation. See the [Task tools reference](https://mastra.ai/reference/tools/task-tools) for full schemas.
+Only one task can be `in_progress` at a time. The list is stored in the thread-scoped `threadState` storage domain and projected onto the agent's [state-signal](https://mastra.ai/docs/harness/signals) lane, so it survives observational-memory truncation. See the [Task tools reference](https://mastra.ai/reference/tools/task-tools) for full schemas.
 
 The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatically includes all built-in tools in every mode, you don't need to add them manually. See [Tool approvals](https://mastra.ai/docs/harness/agent-controller) for AgentController-specific behavior.
 
@@ -651,11 +651,11 @@ The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatic
 
 - [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
 - [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
-- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks): Run long-running tools without blocking the agent loop
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [Background tasks](https://mastra.ai/docs/harness/background-tasks): Run long-running tools without blocking the agent loop
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
 - [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output
-- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent approval](https://mastra.ai/docs/agents/human-in-the-loop)
 - [`askUserTool` reference](https://mastra.ai/reference/tools/ask-user-tool)
 - [`submitPlanTool` reference](https://mastra.ai/reference/tools/submit-plan-tool)
 - [Task tools reference](https://mastra.ai/reference/tools/task-tools)

package/.docs/docs/{server/auth → auth}/custom-auth-provider.md

@@ -509,5 +509,5 @@ See the [source code](https://github.com/mastra-ai/mastra/tree/main/auth) for im
 
 ## Related
 
-- [Auth Overview](https://mastra.ai/docs/server/auth): Authentication concepts and configuration
+- [Auth Overview](https://mastra.ai/docs/auth/overview): Authentication concepts and configuration
 - [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes): Controlling authentication on custom endpoints

package/.docs/docs/{server/auth → auth}/fga.md

@@ -284,6 +284,32 @@ class MyFGAProvider implements IFGAProvider {
 }
 ```
 
+### Propagating an actor into workflow steps
+
+A workflow run's `actor` reaches each step's execute context, but it isn't passed to the agent and tool calls that step makes. Steps that call an agent without an `actor` fall back to user membership resolution, which fails on system runs that have no user.
+
+Set `propagate: true` on the actor to have the framework forward it into the agent and tool calls it makes for declarative `.then(agent)` and `.then(tool)` steps in the run:
+
+```typescript
+await run.start({
+  inputData: { city: 'London' },
+  actor: { actorKind: 'system', sourceWorkflow: 'nightly-report', propagate: true },
+})
+```
+
+Propagation is opt-in and deliberately narrow:
+
+- The `true` shorthand never propagates. Use the object form to opt in.
+- Custom step `execute` functions are never covered. Read `actor` from the step context and pass it explicitly, so a step that acts on a user's behalf can't silently inherit system trust.
+- Pass `actor` when creating the step to override the run actor for that step, including `actor: undefined` to drop back to user authorization mid-run.
+
+```typescript
+// Runs as the system actor even though it loads user-supplied data.
+workflow.then(createStep(reportAgent))
+// Explicitly runs as the user instead.
+workflow.then(createStep(summaryAgent, { actor: undefined }))
+```
+
 ### Trust requirements
 
 The actor signal is trusted input, so construct it server-side:
@@ -299,5 +325,5 @@ The actor signal is trusted input, so construct it server-side:
 ## Related
 
 - [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
-- [Authentication overview](https://mastra.ai/docs/server/auth)
+- [Authentication overview](https://mastra.ai/docs/auth/overview)
 - [WorkOS authentication](https://mastra.ai/integrations/auth/workos)

package/.docs/docs/{server/auth.md → auth/overview.md}

@@ -25,8 +25,8 @@ See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for con
 
 ### Built-in
 
-- [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth)
-- [JSON Web Token](https://mastra.ai/docs/server/auth/jwt)
+- [Simple Auth](https://mastra.ai/docs/auth/simple-auth)
+- [JSON Web Token](https://mastra.ai/docs/auth/jwt)
 
 ### Third-party integrations
 
@@ -41,5 +41,5 @@ See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for con
 
 ### Advanced
 
-- [Composite Auth](https://mastra.ai/docs/server/auth/composite-auth)
-- [Custom Provider](https://mastra.ai/docs/server/auth/custom-auth-provider)
+- [Composite Auth](https://mastra.ai/docs/auth/composite-auth)
+- [Custom Provider](https://mastra.ai/docs/auth/custom-auth-provider)

package/.docs/docs/{server/auth → auth}/simple-auth.md

@@ -171,4 +171,4 @@ SimpleAuth is designed for simplicity, not production security:
 - No cryptographic verification
 - All tokens must be known at startup
 
-For production applications, consider using [JWT](https://mastra.ai/docs/server/auth/jwt), [Clerk](https://mastra.ai/integrations/auth/clerk), [Auth0](https://mastra.ai/integrations/auth/auth0), or another identity provider.
+For production applications, consider using [JWT](https://mastra.ai/docs/auth/jwt), [Clerk](https://mastra.ai/integrations/auth/clerk), [Auth0](https://mastra.ai/integrations/auth/auth0), or another identity provider.

package/.docs/docs/{server/auth → auth}/workers.md

@@ -130,8 +130,8 @@ Your auth provider's `authenticateToken` callback must recognize whatever creden
 
 ## Related
 
-- [Auth overview](https://mastra.ai/docs/server/auth): Available auth providers and how they work
-- [Token-based auth](https://mastra.ai/docs/server/auth/simple-auth): Token-to-user mapping authentication
+- [Auth overview](https://mastra.ai/docs/auth/overview): Available auth providers and how they work
+- [Token-based auth](https://mastra.ai/docs/auth/simple-auth): Token-to-user mapping authentication
 - [Worker deployment](https://mastra.ai/docs/deployment/workers): Set up split worker processes
 - [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`

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

@@ -50,7 +50,7 @@ export const yourAgent = new Agent({
 
 > **Note:** Channel adapters require provider-specific environment variables for credentials and request verification, such as bot tokens, signing secrets, app IDs, and webhook verification tokens. Check the guide for your platform or the [Chat SDK adapter catalog](https://chat-sdk.dev/adapters) for the exact variable names.
 
-We recommend configuring [storage](https://mastra.ai/docs/storage/overview) for channels. Storage lets Mastra persist channel state, thread subscriptions, tool approvals, and memory across restarts:
+We recommend configuring [storage](https://mastra.ai/docs/storage) for channels. Storage lets Mastra persist channel state, thread subscriptions, tool approvals, and memory across restarts:
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -284,7 +284,7 @@ Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soo
 
 ### Coordinate instances with a shared pub/sub
 
-Channels route messages through the agent's [signal pipeline](https://mastra.ai/docs/long-running-agents/signals), and each run acquires a lease on its thread so one run owns the conversation at a time.
+Channels route messages through the agent's [signal pipeline](https://mastra.ai/docs/harness/signals), and each run acquires a lease on its thread so one run owns the conversation at a time.
 
 The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can be routed to a different instance than the one running the agent.
 

package/.docs/docs/{agents → connections}/a2a.md

@@ -80,7 +80,7 @@ Use `A2AAgent` when another Mastra agent should delegate work to a remote agent.
 
 ## Consume A2A agents as subagents
 
-Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/capabilities/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -221,7 +221,7 @@ A2A models human-in-the-loop (HITL) work with the `input-required` task state. W
 
 Mastra maps its agent suspension model to this state in both directions:
 
-- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/agent-approval) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
+- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/human-in-the-loop) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
 - **As a client**: when a remote task reaches `input-required` or `auth-required`, `A2AAgent` returns a suspended result with `finishReason: 'suspended'` and a `suspendPayload`. Calling `resumeGenerate()` or `resumeStream()` sends the input or credentials back to the remote task with the original `taskId`.
 
 ```typescript

package/.docs/docs/{agents → connections}/acp.md

@@ -151,6 +151,6 @@ See the [AcpAgent workspace integration](https://mastra.ai/reference/acp/acp-age
 - [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent)
 - [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
 - [Agent reference](https://mastra.ai/reference/agents/agent)
-- [Subagents](https://mastra.ai/docs/capabilities/subagents)
+- [Subagents](https://mastra.ai/docs/subagents)
 - [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
 - [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/docs/{mcp/overview.md → connections/mcp.md}

@@ -406,7 +406,7 @@ App iframes allow scripts, forms, and popups. They can't access the parent page'
 
 ## Next steps
 
-- [Use tools with agents](https://mastra.ai/docs/agents/using-tools)
+- [Use tools with agents](https://mastra.ai/docs/agents/tools)
 - [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client)
 - [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server)
 - [MCP Apps extension specification](https://github.com/modelcontextprotocol/ext-apps)

package/.docs/docs/connections/overview.md

@@ -4,10 +4,10 @@
 
 Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
 
-- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/agents/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
-- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/agents/acp): Run compatible coding-agent processes as Mastra tools or subagents.
-- [**SDK agents**](https://mastra.ai/docs/agents/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
-- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/mcp/overview): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/connections/mcp): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/connections/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes as Mastra tools or subagents.
+- [**SDK agents**](https://mastra.ai/docs/connections/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
 
 ## When to use connections
 
@@ -20,7 +20,7 @@ Use connections when you need to:
 
 ## Get started
 
-Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/agents/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/agents/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/agents/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/mcp/overview) for tools and resources.
+Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/connections/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/connections/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/connections/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/connections/mcp) for tools and resources.
 
 **A2A**:
 

package/.docs/docs/{agents → connections}/sdk-agents.md

@@ -423,5 +423,5 @@ For storage and dashboard setup, see [Observability](https://mastra.ai/docs/obse
 ## Related
 
 - [Agents overview](https://mastra.ai/docs/agents/overview)
-- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Tools](https://mastra.ai/docs/agents/tools)
 - [Observability](https://mastra.ai/docs/observability/overview)

package/.docs/docs/deployment/mastra-server.md

@@ -102,7 +102,7 @@ If a `public` folder exists in your Mastra directory (`src/mastra/public`), its
 
 ### Mastra configuration
 
-The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](https://mastra.ai/docs/server/mastra-server). For all available options, see the [configuration reference](https://mastra.ai/reference/configuration).
+The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](https://mastra.ai/docs/server/overview). For all available options, see the [configuration reference](https://mastra.ai/reference/configuration).
 
 ## Build process
 
@@ -151,7 +151,7 @@ NODE_OPTIONS="--max-old-space-size=4096" mastra build
 
 ## Related
 
-- [Server Overview](https://mastra.ai/docs/server/mastra-server): Configure server behavior, middleware, and authentication
+- [Server Overview](https://mastra.ai/docs/server/overview): Configure server behavior, middleware, and authentication
 - [Server Adapters](https://mastra.ai/docs/server/server-adapters): Use Express or Hono instead of `mastra build`
 - [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes): Add custom HTTP endpoints
 - [Configuration Reference](https://mastra.ai/reference/configuration): Full configuration options

package/.docs/docs/deployment/overview.md

@@ -17,7 +17,7 @@ Mastra can run against any of these runtime environments:
 
 ### Mastra server
 
-Mastra provides a [server](https://mastra.ai/docs/server/mastra-server) powered by Hono that can be deployed independently. Use the `mastra build` command to build your application and deploy the output to your preferred VM, container, or PaaS platform.
+Mastra provides a [server](https://mastra.ai/docs/server/overview) powered by Hono that can be deployed independently. Use the `mastra build` command to build your application and deploy the output to your preferred VM, container, or PaaS platform.
 
 Use this option when you need full control over your infrastructure, long-running processes, or WebSocket connections. The [Mastra server deployment guide](https://mastra.ai/docs/deployment/mastra-server) provides more details.
 

package/.docs/docs/deployment/sandbox.md

@@ -362,12 +362,12 @@ jobs:
 
 ## Security
 
-- The sandbox URL is public. Anyone with the URL can reach your Mastra server, including Studio. Enable [server auth](https://mastra.ai/docs/server/auth) for anything beyond throwaway previews.
+- The sandbox URL is public. Anyone with the URL can reach your Mastra server, including Studio. Enable [server auth](https://mastra.ai/docs/auth/overview) for anything beyond throwaway previews.
 - Environment variables from your `.env` files are injected into the remote sandbox VM so the server can run. The deploy logs a warning when this happens. Don't deploy secrets you wouldn't put on a shared preview server.
-- To restrict access to Tier 3 traffic, pass a `secret` to `createSandboxHandler()` or `createSandboxProxy()`. The helpers attach it as the `x-mastra-sandbox-secret` header on forwarded requests. Configure [server auth](https://mastra.ai/docs/server/auth) to require that header, and direct hits to the sandbox URL get rejected while traffic through your domain works.
+- To restrict access to Tier 3 traffic, pass a `secret` to `createSandboxHandler()` or `createSandboxProxy()`. The helpers attach it as the `x-mastra-sandbox-secret` header on forwarded requests. Configure [server auth](https://mastra.ai/docs/auth/overview) to require that header, and direct hits to the sandbox URL get rejected while traffic through your domain works.
 
 ## Related
 
 - [Deployment overview](https://mastra.ai/docs/deployment/overview)
-- [Server authentication](https://mastra.ai/docs/server/auth)
+- [Server authentication](https://mastra.ai/docs/auth/overview)
 - [`WorkspaceSandbox` reference](https://mastra.ai/reference/workspace/sandbox)

package/.docs/docs/deployment/workers.md

@@ -339,7 +339,7 @@ MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 
 Without this variable, the orchestration worker attempts to execute steps in its own process, which doesn't have access to the full Mastra runtime in a split deployment.
 
-The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/server/auth/workers) for server configuration and other credential formats.
+The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/auth/workers) for server configuration and other credential formats.
 
 ### Scale workers
 
@@ -365,18 +365,18 @@ A distributed PubSub backend persists unacknowledged events, which lets orchestr
 
 The scheduler calculates the next fire time from the current time after it restarts. It doesn't replay schedules that elapsed while it was unavailable.
 
-If the API crashes while a step is executing, that work can be lost and the workflow run can remain in a `running` state. See [known limitations](#known-limitations) and [durable agent crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents).
+If the API crashes while a step is executing, that work can be lost and the workflow run can remain in a `running` state. See [known limitations](#known-limitations) and [durable agent crash recovery](https://mastra.ai/docs/harness/durable-agents).
 
 ## Known limitations
 
 - **No dead-letter queue**: Failed events are nacked and retried, but there's no DLQ for events that fail after all retries.
 - **No built-in health endpoint**: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
 - **Scheduler is single-instance**: Running multiple scheduler processes causes duplicate schedule fires.
-- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents) for details.
+- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/harness/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/harness/durable-agents) for details.
 
 ## Related
 
-- [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
+- [Worker authentication](https://mastra.ai/docs/auth/workers): Secure worker-to-API communication
 - [Workers reference](https://mastra.ai/reference/workers/overview): Details about worker environment variables and types, with a list of supported storage backends
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends

package/.docs/docs/guides/multi-agent-systems.md

@@ -44,7 +44,7 @@ A supervisor pattern keeps one lead agent in control for the full task. The supe
 
 Use this pattern when the task is open-ended and the full sequence isn't known in advance. For example, a research task may require different lines of inquiry based on what earlier steps uncover. A supervisor can adapt as the task unfolds. The tradeoff is that the supervisor becomes the main coordination point. That makes the pattern flexible, but it also means the result depends heavily on good delegation behavior and clear subagent boundaries.
 
-In Mastra, this pattern maps directly to [supervisor agents](https://mastra.ai/docs/capabilities/subagents). A supervisor agent defines subagents on the `agents` property and uses `stream()` or `generate()` to coordinate them. Mastra also provides delegation hooks, message filtering, and memory isolation to help control this pattern.
+In Mastra, this pattern maps directly to [supervisor agents](https://mastra.ai/docs/subagents). A supervisor agent defines subagents on the `agents` property and uses `stream()` or `generate()` to coordinate them. Mastra also provides delegation hooks, message filtering, and memory isolation to help control this pattern.
 
 > **Tip:** Follow the [supervisor agents tutorial](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents) for a step-by-step guide.
 
@@ -60,12 +60,12 @@ Mastra doesn't provide a dedicated council primitive. In Mastra, implement this
 
 These patterns differ mainly in how they distribute control:
 
-| Pattern           | Who stays in control | Use when                                         | Tradeoff                                                 | Mastra implementation                                              |
-| ----------------- | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------ |
-| Handoffs          | Current specialist   | Ownership should move between specialists        | Context transfer becomes more important                  | Agents with workflows and memory                                   |
-| Workflows         | Execution graph      | The path is known in advance                     | Less adaptive when the task changes                      | [Workflows](https://mastra.ai/docs/workflows/overview)             |
-| Supervisor agents | One lead agent       | Delegation must adapt during execution           | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) |
-| Council           | Final synthesis step | The task needs multiple independent perspectives | Higher cost and latency                                  | Agents with workflow parallelism                                   |
+| Pattern           | Who stays in control | Use when                                         | Tradeoff                                                 | Mastra implementation                                  |
+| ----------------- | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------ |
+| Handoffs          | Current specialist   | Ownership should move between specialists        | Context transfer becomes more important                  | Agents with workflows and memory                       |
+| Workflows         | Execution graph      | The path is known in advance                     | Less adaptive when the task changes                      | [Workflows](https://mastra.ai/docs/workflows/overview) |
+| Supervisor agents | One lead agent       | Delegation must adapt during execution           | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/subagents)  |
+| Council           | Final synthesis step | The task needs multiple independent perspectives | Higher cost and latency                                  | Agents with workflow parallelism                       |
 
 In practice, these patterns are often combined:
 

package/.docs/docs/guides/streaming.md

@@ -31,7 +31,7 @@ for await (const chunk of stream.textStream) {
 
 Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
-> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
+> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/harness/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
 
 ### Output from `Agent.stream()`
 

package/.docs/docs/harness/agent-controller.md

@@ -8,6 +8,8 @@
 
 [Mastra Code](https://code.mastra.ai) and [Mastra Factory](https://factory.mastra.ai) are the flagship AgentController implementations. They're coding agents with multi-model support, persistent conversations, and plan-then-execute workflows. Read [Building a coding agent](https://mastra.ai/blog/building-a-coding-agent) for a step-by-step TUI guide.
 
+When the agent you host works in a codebase, build it with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) instead of `new Agent()`. It returns a standard `Agent` that already has a workspace, task tracking, and retries for transient model errors, which are the defaults Mastra Code runs on.
+
 ## When to use the Agent Controller
 
 Use the Agent Controller when your application needs:
@@ -388,7 +390,7 @@ channels: {
 
 Controller channel sessions and auto-approval state are held in memory, so use a long-lived server. Pending approvals and live Session state don't survive process restarts. Adapters that can't render approval controls automatically run tools without an approval prompt so the run doesn't remain suspended.
 
-See [Channels](https://mastra.ai/docs/capabilities/channels) for adapter setup and platform-specific webhook configuration.
+See [Channels](https://mastra.ai/docs/channels) for adapter setup and platform-specific webhook configuration.
 
 ## Connect a UI
 
@@ -412,6 +414,6 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 ## Related
 
 - [Agents](https://mastra.ai/docs/agents/overview)
-- [Workspace](https://mastra.ai/docs/workspace/sandbox)
+- [Workspace](https://mastra.ai/docs/sandbox/overview)
 - [Observational memory](https://mastra.ai/docs/memory/observational-memory)
-- [Channels](https://mastra.ai/docs/capabilities/channels)
+- [Channels](https://mastra.ai/docs/channels)

package/.docs/docs/{long-running-agents → harness}/background-tasks.md

@@ -16,7 +16,7 @@ Use background tasks when a tool call may take long enough that the user shouldn
 
 For tool calls that return quickly, foreground execution using `agent.stream()` and `agent.generate()` is simpler.
 
-> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/storage/overview) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
+> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/storage) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
 
 ## Quickstart
 
@@ -121,7 +121,7 @@ If the agent has `backgroundTasks.disabled: true`, every tool call runs synchron
 
 ## Background tasks related stream chunks
 
-When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/long-running-agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
+When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/harness/background-tasks) SSE stream. Each stream covers a different set of chunk types:
 
 | Chunk type                  | When it fires                                                                          | Emitted by     |
 | --------------------------- | -------------------------------------------------------------------------------------- | -------------- |
@@ -376,7 +376,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
-- [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
-- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
+- [Durable agents](https://mastra.ai/docs/harness/durable-agents)
+- [Supervisor agents](https://mastra.ai/docs/subagents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
-- [Storage](https://mastra.ai/docs/storage/overview)
+- [Storage](https://mastra.ai/docs/storage)