@mastra/mcp-docs-server 1.2.17-alpha.11 → 1.2.17-alpha.14

package/.docs/reference/auth/fga.md

@@ -4,7 +4,7 @@
 
 The `IFGAProvider` interface defines a fine-grained authorization (FGA) provider. Mastra calls it to decide whether a user or a system actor may perform a permission on a specific resource. Implement it to connect Mastra to an FGA backend, such as WorkOS Authorization.
 
-For concepts, configuration, and the lifecycle points where Mastra enforces FGA, see [Fine-grained authorization](https://mastra.ai/docs/server/auth/fga).
+For concepts, configuration, and the lifecycle points where Mastra enforces FGA, see [Fine-grained authorization](https://mastra.ai/docs/auth/fga).
 
 ## Usage example
 
@@ -47,7 +47,7 @@ Returns: `Promise<boolean>`
 
 ### `require(user, params)`
 
-Throws `FGADeniedError` when `user` lacks the permission. Mastra calls this at its [enforcement points](https://mastra.ai/docs/server/auth/fga).
+Throws `FGADeniedError` when `user` lacks the permission. Mastra calls this at its [enforcement points](https://mastra.ai/docs/auth/fga).
 
 Returns: `Promise<void>`
 
@@ -63,7 +63,7 @@ Authorizes a non-user system actor, such as an autonomous or scheduled agent. Op
 
 System actors skip the user-centric `require()` path, so implement `requireActor` to enforce per-agent least privilege for them. Throw `FGADeniedError` to deny. When a provider doesn't implement `requireActor`, Mastra preserves the trusted-actor bypass (allow after the tenant-scope check), so adding the method remains backward compatible.
 
-Treat `actor.permissions` as an untrusted claim. Resolve the agent's authoritative grants from a trusted source keyed by `actor.agentId`, rather than trusting the inline values. See [System actors](https://mastra.ai/docs/server/auth/fga).
+Treat `actor.permissions` as an untrusted claim. Resolve the agent's authoritative grants from a trusted source keyed by `actor.agentId`, rather than trusting the inline values. See [System actors](https://mastra.ai/docs/auth/fga).
 
 ```typescript
 import { FGADeniedError } from '@mastra/core/auth/ee'
@@ -135,6 +135,6 @@ throw new FGADeniedError(user, { type: 'agent', id: 'reporter' }, 'agents:execut
 
 ## Related
 
-- [Fine-grained authorization](https://mastra.ai/docs/server/auth/fga)
-- [System actors](https://mastra.ai/docs/server/auth/fga)
+- [Fine-grained authorization](https://mastra.ai/docs/auth/fga)
+- [System actors](https://mastra.ai/docs/auth/fga)
 - [WorkOS authentication](https://mastra.ai/reference/auth/workos)

package/.docs/reference/auth/jwt.md

@@ -25,4 +25,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-- [JSON Web Token](https://mastra.ai/docs/server/auth/jwt)
+- [JSON Web Token](https://mastra.ai/docs/auth/jwt)

package/.docs/reference/browser/agent-browser.md

@@ -54,7 +54,7 @@ then interact with elements using their refs (e.g., @e5).`,
 
 `AgentBrowser` provides 16 deterministic tools for browser automation. All tools that interact with elements use refs from the accessibility tree snapshot.
 
-When `recording` is configured, `AgentBrowser` also adds the Beta `browser_record` and `browser_record_caption` tools. See [Browser recording (Beta)](https://mastra.ai/docs/browser/overview).
+When `recording` is configured, `AgentBrowser` also adds the Beta `browser_record` and `browser_record_caption` tools. See [Browser recording (Beta)](https://mastra.ai/docs/browser).
 
 ### Core tools
 
@@ -403,5 +403,5 @@ The `browser_snapshot` tool returns an accessibility tree with element refs like
 
 - [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class reference
 - [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser): AI-powered alternative
-- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide
+- [Browser overview](https://mastra.ai/docs/browser): Conceptual guide
 - [agent-browser guide](https://mastra.ai/integrations/browsers/agent-browser): Usage guide

package/.docs/reference/browser/browser-viewer.md

@@ -194,7 +194,7 @@ await viewer.injectKeyboardEvent({
 
 ## Supported CLIs
 
-Each CLI must be installed separately. Each also publishes a [skill](https://mastra.ai/docs/workspace/skills) that teaches the agent its commands and workflows. When a CLI command runs through `workspace_execute_command`, Mastra detects it and injects the CDP URL automatically using the correct flag.
+Each CLI must be installed separately. Each also publishes a [skill](https://mastra.ai/docs/sandbox/skills) that teaches the agent its commands and workflows. When a CLI command runs through `workspace_execute_command`, Mastra detects it and injects the CDP URL automatically using the correct flag.
 
 Unlike SDK providers, `BrowserViewer` doesn't provide agent tools. The agent uses CLI commands through `workspace_execute_command` instead.
 
@@ -229,4 +229,4 @@ browse skills install
 
 - [BrowserViewer guide](https://mastra.ai/integrations/browsers/browser-viewer): Setup and usage walkthrough
 - [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class API reference
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox): Workspace configuration
+- [Sandbox](https://mastra.ai/docs/sandbox/overview): Workspace configuration

package/.docs/reference/browser/firecrawl-browser.md

@@ -68,4 +68,4 @@ In both cases, `FirecrawlBrowser` deletes the remote Firecrawl session when the
 
 - [Firecrawl docs](https://mastra.ai/integrations/browsers/firecrawl)
 - [`AgentBrowser` reference](https://mastra.ai/reference/browser/agent-browser)
-- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [Browser overview](https://mastra.ai/docs/browser)

package/.docs/reference/browser/mastra-browser.md

@@ -285,4 +285,4 @@ const browser = new AgentBrowser({
 
 - [AgentBrowser](https://mastra.ai/reference/browser/agent-browser): Deterministic browser automation
 - [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser): AI-powered browser automation
-- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide to browser automation
+- [Browser overview](https://mastra.ai/docs/browser): Conceptual guide to browser automation

package/.docs/reference/browser/stagehand-browser.md

@@ -71,7 +71,7 @@ Use stagehand_extract to get data from pages.`,
 
 `StagehandBrowser` provides 7 AI-powered tools for browser automation.
 
-When `recording` is configured, `StagehandBrowser` also adds the Beta `browser_record` and `browser_record_caption` tools. See [Browser recording (Beta)](https://mastra.ai/docs/browser/overview).
+When `recording` is configured, `StagehandBrowser` also adds the Beta `browser_record` and `browser_record_caption` tools. See [Browser recording (Beta)](https://mastra.ai/docs/browser).
 
 Core tools:
 
@@ -316,5 +316,5 @@ Choose `AgentBrowser` for precise, reproducible automation. Choose `StagehandBro
 
 - [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class reference
 - [AgentBrowser](https://mastra.ai/reference/browser/agent-browser): Deterministic alternative
-- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide
+- [Browser overview](https://mastra.ai/docs/browser): Conceptual guide
 - [Stagehand guide](https://mastra.ai/integrations/browsers/stagehand): Usage guide

package/.docs/reference/build-with-ai.md

@@ -2,7 +2,7 @@
 
 # Build with AI
 
-For everyday AI-assisted development with Mastra skills and the CLI, see [Develop](https://mastra.ai/docs/getting-started/develop). This page covers other ways to give coding agents access to Mastra documentation.
+For everyday AI-assisted development with Mastra skills and the CLI, see [Develop](https://mastra.ai/docs/develop). This page covers other ways to give coding agents access to Mastra documentation.
 
 ## Embedded package docs
 
@@ -29,7 +29,7 @@ Examples for the [introduction page](https://mastra.ai/docs):
 
 ## MCP docs server
 
-> **Warning:** The MCP docs server isn't recommended for everyday development. Use the [Mastra skill](https://mastra.ai/docs/getting-started/develop) instead because it's more up to date and performs better.
+> **Warning:** The MCP docs server isn't recommended for everyday development. Use the [Mastra skill](https://mastra.ai/docs/develop) instead because it's more up to date and performs better.
 
 The `@mastra/mcp-docs-server` package provides direct local access to Mastra’s full documentation via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It works with Cursor, Windsurf, Cline, Claude Code, VS Code, Codex or any tool that supports MCP.
 

package/.docs/reference/channels/channel-provider.md

@@ -64,4 +64,4 @@ const all = mastra.getChannelProviders()
 ## Related
 
 - [SlackProvider](https://mastra.ai/reference/channels/slack-provider)
-- [Channels](https://mastra.ai/docs/capabilities/channels)
+- [Channels](https://mastra.ai/docs/channels)

package/.docs/reference/channels/slack-provider.md

@@ -226,5 +226,5 @@ const result = await slack.connect('support-agent')
 ## Related
 
 - [ChannelProvider](https://mastra.ai/reference/channels/channel-provider): the interface `SlackProvider` implements
-- [Channels](https://mastra.ai/docs/capabilities/channels): concepts, platform setup, and the `createSlackAdapter` path
+- [Channels](https://mastra.ai/docs/channels): concepts, platform setup, and the `createSlackAdapter` path
 - [Channels reference](https://mastra.ai/reference/agents/channels): the `channels` config on the `Agent` constructor

package/.docs/reference/cli/mastra.md

@@ -1771,6 +1771,8 @@ When a server started with `mastra dev` or `mastra start` has observability metr
 
 At server startup, Mastra also sends an anonymous project-surface snapshot: counts of registered agents, agent controllers, workflows, tools, processors, vector stores, scorers, workspaces, MCP servers, gateways, and channels, plus booleans for memory, voice, editor, and observability usage and the coarse storage backend category. It doesn't send names or identifiers. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts) to check what's collected.
 
+The Studio UI also collects anonymous browser-side usage analytics, such as page views and UI interactions. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/playground/src/lib/analytics.tsx) to check what's collected. Setting `MASTRA_TELEMETRY_DISABLED` disables this too: the value is injected into the served page, so it applies to `mastra dev` and self-hosted builds alike.
+
 You can opt out of all CLI and usage analytics by setting an environment variable:
 
 ```bash

package/.docs/reference/client-js/agents.md

@@ -285,7 +285,7 @@ await subscription.processDataStream({
 
 ### `streamUntilIdle()`
 
-Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `stream()`.
+Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/harness/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `stream()`.
 
 ```typescript
 const response = await agent.streamUntilIdle('Research solana for me', {
@@ -307,7 +307,7 @@ response.processDataStream({
 
 ### `resumeStreamUntilIdle()`
 
-Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `resumeStream()`:
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/harness/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `resumeStream()`:
 
 ```typescript
 const response = await agent.resumeStreamUntilIdle(
@@ -497,7 +497,7 @@ if (output.finishReason === 'suspended') {
 
 ## Agent schedules
 
-Use the client SDK schedule methods to manage persisted agent schedules over the `/api/schedules` routes. For concepts and server-side examples, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules) and the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
+Use the client SDK schedule methods to manage persisted agent schedules over the `/api/schedules` routes. For concepts and server-side examples, see [Schedules](https://mastra.ai/docs/harness/schedules) and the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
 
 ### `createSchedule()`
 
@@ -839,7 +839,7 @@ console.log(result.success) // true
 
 ## Version management
 
-Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See [Editor versioning](https://mastra.ai/docs/editor/overview) for lifecycle and selection behavior.
+Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See [Editor versioning](https://mastra.ai/docs/studio/editor) for lifecycle and selection behavior.
 
 ### Getting an agent with a specific version
 

package/.docs/reference/coding-agent/create-coding-agent.md

@@ -2,13 +2,17 @@
 
 # createCodingAgent()
 
-`createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only `model`, `instructions`, and `tools` to get a working agent, or override any default.
+**Added in:** `@mastra/core@1.48.0`
 
-The returned value is a standard `Agent`, so it works anywhere an `Agent` does: including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+`createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with the essential defaults a coding agent always needs: a local workspace, the task-list signal provider when `memory` is configured, network-retry error processors, and the goal judge prompt. Supply only `model` and `instructions` to get a working agent, or override any default.
+
+The returned value is a standard `Agent`, so it works anywhere an `Agent` does: including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class). The function lives in `@mastra/core` with no hosted service behind it, and every default it fills in is a primitive you can also configure on [`new Agent()`](https://mastra.ai/reference/agents/agent) yourself.
+
+The defaults match the ones [Mastra Code](https://code.mastra.ai) runs on. The prompt, modes, and tools that make up that product aren't included: `createCodingAgent()` sets up only the runtime pieces listed under [Defaults](#defaults).
 
 ## Usage example
 
-Pass a model, instructions, and tools. The factory fills in the workspace, task signal, error processors, and goal prompt:
+Pass a model and instructions. `createCodingAgent()` fills in the workspace and the error processors. The task signal provider is added when `memory` is configured, and the goal prompt when a `goal` is configured:
 
 ```typescript
 import { createCodingAgent } from '@mastra/core/coding-agent'
@@ -18,13 +22,20 @@ const agent = createCodingAgent({
   name: 'My Coding Agent',
   model: 'openai/gpt-5',
   instructions: 'You are a helpful coding assistant.',
-  tools: {},
 })
+
+const result = await agent.generate('Which test files mention the /health endpoint?')
 ```
 
+The agent receives the [workspace tools](https://mastra.ai/reference/workspace/workspace-class) for its resolved workspace, so `tools` is only needed for capabilities beyond the workspace, such as opening a pull request. Mastra also adds a description of the workspace to the system prompt.
+
+> **Warning:** The default workspace runs commands on the host machine with the permissions of your application process. See [Workspace](#workspace) for how to swap in an isolated sandbox.
+
+For the behavioral prompt Mastra Code uses, covering repository exploration, edits, commands, and commits, build `instructions` with [`buildBasePrompt()`](https://mastra.ai/reference/coding-agent/build-base-prompt).
+
 ## Parameters
 
-`createCodingAgent()` accepts every field of [`AgentConfig`](https://mastra.ai/reference/agents/agent) plus the fields below. Fields you provide always take precedence over the factory defaults.
+`createCodingAgent()` accepts every field of [`AgentConfig`](https://mastra.ai/reference/agents/agent) plus the fields below. Fields you provide replace the corresponding default, except for `signals`: the default task signal provider is merged into the providers you pass. See [Signals](#signals).
 
 **model** (`MastraLanguageModel | DynamicArgument<MastraLanguageModel>`): The language model the agent uses. Passed straight through to Agent.
 
@@ -32,11 +43,11 @@ const agent = createCodingAgent({
 
 **tools** (`ToolsInput | DynamicArgument<ToolsInput>`): Tools available to the agent. Passed straight through to Agent.
 
-**workspace** (`AnyWorkspace | undefined`): The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, the factory builds no default — opt out when the workspace is wired elsewhere (for example at the AgentController level).
+**workspace** (`AnyWorkspace | undefined`): The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, no default is built. Opt out this way when the workspace is wired elsewhere, for example at the AgentController level.
 
 **basePath** (`string`): Base path for the default workspace built when workspace is omitted. (Default: `process.cwd()`)
 
-**signals** (`SignalProvider[]`): Signal providers for the agent. When omitted, defaults to a single TaskSignalProvider.
+**signals** (`SignalProvider[]`): Signal providers for the agent. A TaskSignalProvider is added only when memory is configured, and it is merged into the providers you pass rather than replacing them. Without memory, the agent gets exactly the providers you pass, or none.
 
 **errorProcessors** (`Processor[]`): Error processors for the agent. When omitted, defaults to unknown stream-error retries with specialized ECONNRESET and bad-request policies, plus PrefillErrorHandler and ProviderHistoryCompat.
 
@@ -48,18 +59,29 @@ const agent = createCodingAgent({
 
 ## Defaults
 
-The factory only fills a default when you don't provide the corresponding field. Caller-provided values always win.
+A default is only filled in when you don't provide the corresponding field. `signals` is the exception: the task signal provider is appended to the providers you pass.
 
 | Field             | Default when omitted                                                                                                                           |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `workspace`       | A [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) backed by `LocalFilesystem` and `LocalSandbox` rooted at the base path. |
-| `signals`         | A single [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider).                                                     |
+| `signals`         | A [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), added only when `memory` is configured.                    |
 | `errorProcessors` | Unknown stream-error retries with specialized ECONNRESET and bad-request policies, plus `PrefillErrorHandler` and `ProviderHistoryCompat`.     |
 | `goal.prompt`     | `DEFAULT_GOAL_JUDGE_PROMPT` (only when a `goal` is configured).                                                                                |
 
+Nothing else is filled in. There's no default `model`, `instructions`, `tools`, `memory`, storage, or input and output processors.
+
+Each default has an explicit opt-out:
+
+| Default           | How to opt out                              |
+| ----------------- | ------------------------------------------- |
+| Workspace         | `workspace: undefined`                      |
+| Task tracking     | Don't configure `memory` on the agent       |
+| Error processors  | `errorProcessors: []`                       |
+| Goal judge prompt | Omit `goal`, or pass your own `goal.prompt` |
+
 ### Workspace
 
-When the `workspace` key is omitted, the factory builds a local workspace rooted at `basePath` (default `process.cwd()`):
+When the `workspace` key is omitted, a local workspace rooted at `basePath` (default `process.cwd()`) is built:
 
 ```typescript
 import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
@@ -70,19 +92,94 @@ new Workspace({
 })
 ```
 
-To opt out (for example, when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level), pass `workspace: undefined` explicitly:
+To keep that shape but work in a different directory, pass `basePath`:
 
 ```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  basePath: '/srv/checkouts/my-app',
+})
+```
+
+Pass a `workspace` to build the backends yourself. Here the agent reads the whole repository while commands run inside one package. A remote sandbox takes the place of `LocalSandbox` in the same slot, see [Sandbox](https://mastra.ai/docs/sandbox/overview) for the available backends and isolation options:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { LocalFilesystem, LocalSandbox, Workspace } from '@mastra/core/workspace'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  workspace: new Workspace({
+    filesystem: new LocalFilesystem({ basePath: '/srv/checkouts/my-app' }),
+    sandbox: new LocalSandbox({ workingDirectory: '/srv/checkouts/my-app/packages/api' }),
+  }),
+})
+```
+
+To opt out (for example, when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level), pass `workspace: undefined` explicitly. An omitted key builds the default, an explicit `undefined` builds nothing:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+
 const agent = createCodingAgent({
   id: 'my-coding-agent',
   name: 'My Coding Agent',
   model: 'openai/gpt-5',
   instructions: 'You are a helpful coding assistant.',
-  tools: {},
   workspace: undefined, // opt out of the default workspace
 })
 ```
 
+### Signals
+
+[`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider) adds the `task_write`, `task_update`, `task_complete`, and `task_check` [task tools](https://mastra.ai/reference/tools/task-tools) and persists the list in thread state, which gives the agent a durable plan across a multi-step request:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { Memory } from '@mastra/memory'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'Plan multi-step work with the task tools, then carry it out.',
+  memory: new Memory(),
+})
+```
+
+The provider needs a memory-backed thread, so it's only added when `memory` is configured. With memory configured, the provider is merged into any `signals` you pass, which keeps task tracking from being dropped by custom providers. Passing `signals: []` alongside `memory` still yields the task provider. To run a memory-backed agent with no task tracking, configure the agent with [`new Agent()`](https://mastra.ai/reference/agents/agent) instead. Before `@mastra/core@1.49.0`, the provider was always added, which failed in memoryless contexts.
+
+`TaskSignalProvider` takes no constructor arguments, so customizing this default means choosing which other providers the agent gets:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { WebhookSignalProvider } from '@mastra/core/signals'
+import { Memory } from '@mastra/memory'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  memory: new Memory(),
+  signals: [
+    new WebhookSignalProvider({
+      extractResourceId: payload => (payload as { repository: string }).repository,
+    }),
+  ],
+})
+```
+
+That agent gets the webhook provider and the task provider.
+
 ### Error processors
 
 The default [`StreamErrorRetryProcessor`](https://mastra.ai/reference/processors/stream-error-retry-processor) applies these retry policies:
@@ -91,10 +188,42 @@ The default [`StreamErrorRetryProcessor`](https://mastra.ai/reference/processors
 - Network resets (`ECONNRESET` / `socket hang up`) retry up to twice with exponential backoff (`1000ms * 2^retryCount`, capped at `30000ms`).
 - Bad-request errors retry once after `2000ms`.
 
-Specific network-reset and bad-request policies take precedence over the unknown-error policy. Passing `errorProcessors` replaces the default processor stack. `PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility.
+Specific network-reset and bad-request policies take precedence over the unknown-error policy. Passing `errorProcessors` replaces the default processor stack. `PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility: both repair errors caused by the shape of the message history, such as a provider rejecting a conversation that ends with an assistant message.
+
+Retries happen inside the `generate()` or `stream()` call that hit the error, so a recovered failure is invisible to your code. When the retries run out, the error surfaces the way any model error does: `generate()` rejects and `stream()` emits an `error` chunk. `generate()` and `stream()` also accept `errorProcessors` per call, which replaces the agent's stack for that request. See [Processors](https://mastra.ai/docs/agents/processors) for `maxProcessorRetries`, the retry budget these processors share.
+
+### Goal
+
+No goal is configured by default. When you pass a `goal` without a `prompt`, `DEFAULT_GOAL_JUDGE_PROMPT` is used. The `goal` config carries the judge and the run budget, while the objective itself is per thread and set with [`setObjective()`](https://mastra.ai/docs/harness/goals):
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { Memory } from '@mastra/memory'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  memory: new Memory(),
+  goal: {
+    judge: 'openai/gpt-5-mini',
+    maxRuns: 50,
+  },
+})
+
+const threadId = 'thread-1'
+const resourceId = 'user-1'
+
+await agent.setObjective('Get the test suite passing', { threadId, resourceId })
+```
+
+[Goals](https://mastra.ai/docs/harness/goals) require a [storage](https://mastra.ai/docs/storage) backend and a memory-backed thread. Without a resolved `judge`, the goal step is a no-op.
 
 ## Related
 
 - [`buildBasePrompt()`](https://mastra.ai/reference/coding-agent/build-base-prompt)
+- [Goals](https://mastra.ai/docs/harness/goals)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)
 - [`Agent`](https://mastra.ai/reference/agents/agent)
 - [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/reference/configuration.md

@@ -44,7 +44,7 @@ export const mastra = new Mastra({
 
 Enables and configures the background task manager. When enabled, agents can dispatch long-running tool calls (including subagent invocations) to run asynchronously while the agentic loop continues. Tasks are persisted, so a configured `storage` backend is required.
 
-Visit the [Background tasks documentation](https://mastra.ai/docs/long-running-agents/background-tasks) to learn more.
+Visit the [Background tasks documentation](https://mastra.ai/docs/harness/background-tasks) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -219,7 +219,7 @@ export const mastra = new Mastra({
 
 MCP (Model Context Protocol) servers that expose Mastra tools, agents, workflows, and resources to MCP-compatible clients. Use this to author your own MCP servers that can be consumed by any system that supports the protocol.
 
-Visit the [MCP Overview](https://mastra.ai/docs/mcp/overview) to learn more.
+Visit the [MCP Overview](https://mastra.ai/docs/connections/mcp) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -366,7 +366,7 @@ export const mastra = new Mastra({
 
 Storage provider for persisting application data. Used by memory, workflows, traces, and other components that require persistence. Mastra supports multiple database backends including PostgreSQL, MongoDB, libSQL, and more.
 
-Visit the [Storage documentation](https://mastra.ai/docs/storage/overview) to learn more.
+Visit the [Storage documentation](https://mastra.ai/docs/storage) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -386,7 +386,7 @@ export const mastra = new Mastra({
 
 Tools are reusable functions that agents can use to interact with external systems. Each tool defines inputs, outputs, and execution logic.
 
-Visit the [Tools documentation](https://mastra.ai/docs/agents/using-tools) to learn more.
+Visit the [Tools documentation](https://mastra.ai/docs/agents/tools) to learn more.
 
 > **Note:** Most users configure tools directly on agents. This top-level configuration is for defining reusable tools that can be shared across multiple agents.
 
@@ -483,7 +483,7 @@ export const mastra = new Mastra({
 
 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents inherit the global workspace on the `Mastra` class unless they have their own workspace configured.
 
-See the [Workspace documentation](https://mastra.ai/docs/workspace/sandbox) for implementation details.
+See the [Workspace documentation](https://mastra.ai/docs/sandbox/overview) for implementation details.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -618,7 +618,7 @@ export const mastra = new Mastra({
 
 Authentication configuration for the server. Mastra supports multiple authentication providers including JWT, Clerk, Supabase, Firebase, WorkOS, and Auth0.
 
-Visit the [Authentication documentation](https://mastra.ai/docs/server/auth) to learn more.
+Visit the [Authentication documentation](https://mastra.ai/docs/auth/overview) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/core/getEditor.md

@@ -33,5 +33,5 @@ This method doesn't accept any parameters.
 
 ## Related
 
-- [Editor](https://mastra.ai/docs/editor/overview)
+- [Editor](https://mastra.ai/docs/studio/editor)
 - [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor)

package/.docs/reference/core/getMCPServer.md

@@ -43,5 +43,5 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
 
 ## See also
 
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/getMCPServerById.md

@@ -51,5 +51,5 @@ const serverByKey = mastra.getMCPServer('customKey')
 
 ## See also
 
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/getTool.md

@@ -27,7 +27,7 @@ const tool = mastra.getTool('weather')
 
 ## Related
 
-- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Share tools across agents](https://mastra.ai/docs/agents/tools)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)
 - [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/getToolById.md

@@ -42,7 +42,7 @@ const toolById = mastra.getToolById('weather-tool')
 
 ## Related
 
-- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Share tools across agents](https://mastra.ai/docs/agents/tools)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
 - [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/listMCPServers.md

@@ -49,5 +49,5 @@ This method doesn't accept any parameters.
 
 ## See also
 
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/listTools.md

@@ -32,7 +32,7 @@ This method lists the Mastra-level registry. It doesn't include tools that exist
 
 ## Related
 
-- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Share tools across agents](https://mastra.ai/docs/agents/tools)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
 - [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)

package/.docs/reference/core/removeWorkspace.md

@@ -24,5 +24,5 @@ When `destroy` is `true` and `workspace.destroy()` throws, the call rejects with
 
 ## Related
 
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/reference/editor/mastra-editor.md

@@ -4,7 +4,7 @@
 
 The `MastraEditor` class sets up the editor system. Pass it to the `Mastra` constructor to turn on editor features like prompt blocks, agent code override, versioning, and tool providers.
 
-See [Editor](https://mastra.ai/docs/editor/overview) for an introduction to what the editor does.
+See [Editor](https://mastra.ai/docs/studio/editor) for an introduction to what the editor does.
 
 ## Usage example
 
@@ -238,4 +238,4 @@ const source = mastra.getEditor()?.getSource()
 
 Returns: `'code' | 'db' | undefined`
 
-When `source` is omitted, Editor uses the configured database storage even though `getSource()` returns `undefined`. See [Editor storage options](https://mastra.ai/docs/editor/overview) for the storage workflows and [code-source versioning](https://mastra.ai/reference/editor/versioning) for activation and Git history behavior.
+When `source` is omitted, Editor uses the configured database storage even though `getSource()` returns `undefined`. See [Editor storage options](https://mastra.ai/docs/studio/editor) for the storage workflows and [code-source versioning](https://mastra.ai/reference/editor/versioning) for activation and Git history behavior.

package/.docs/reference/editor/prompt-blocks.md

@@ -4,7 +4,7 @@
 
 Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text with embedded prompt blocks and references to independently versioned prompt blocks.
 
-See [Prompt blocks](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+See [Prompt blocks](https://mastra.ai/docs/studio/editor) for the Studio workflow and common uses.
 
 ## Block types
 
@@ -134,4 +134,4 @@ The default Mastra server prefix is `/api`. A custom server prefix changes the p
 
 ## Version resolution
 
-Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/editor/overview) for the shared draft, publish, and restore lifecycle.
+Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/studio/editor) for the shared draft, publish, and restore lifecycle.

package/.docs/reference/editor/tool-provider.md

@@ -4,7 +4,7 @@
 
 The `ToolProvider` interface defines how the editor discovers and resolves integration tools from external platforms. Mastra includes two built-in implementations: `ComposioToolProvider` and `ArcadeToolProvider`.
 
-See [Editor tools](https://mastra.ai/docs/editor/overview) for provider setup and the Studio workflow. See [tool configuration](https://mastra.ai/reference/editor/tools) for stored selections and resolution behavior.
+See [Editor tools](https://mastra.ai/docs/studio/editor) for provider setup and the Studio workflow. See [tool configuration](https://mastra.ai/reference/editor/tools) for stored selections and resolution behavior.
 
 ## ToolProvider interface
 

package/.docs/reference/editor/tools.md

@@ -4,7 +4,7 @@
 
 Editor stores tool selections as part of an agent version. A stored configuration can add registered tools and tools from integration providers, as well as tools from Model Context Protocol (MCP) clients.
 
-See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+See [Editor tools](https://mastra.ai/docs/studio/editor) for the Studio workflow and common uses.
 
 ## Tool sources