@mastra/mcp-docs-server 1.2.13-alpha.0 → 1.2.13-alpha.11

package/.docs/docs/agents/agent-approval.md

@@ -104,6 +104,78 @@ A tool's own `requireApproval` setting takes precedence over the function above.
 
 > **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
 
+#### Bind approval to the exact tool arguments
+
+For sensitive tools, bind the approval to the exact tool name and arguments that were shown to the reviewer. If those arguments drift before execution, the tool shouldn't run under the old approval.
+
+The `tool-call-approval` chunk already includes `toolName`, `toolCallId`, and `args`. You can fingerprint those fields when the approval request is shown. The example below uses a JSON string as the fingerprint, but in production you should use a stable hash of the tool name and arguments:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// For your production usecase, build a stable hash of the tool name and args
+function actionFingerprint(toolName: string, args: unknown) {
+  const payload = JSON.stringify({ toolName, args })
+  return `fingerprint-${payload}`
+}
+
+const sensitiveTools = new Set(['issue_refund', 'delete_record'])
+const approvedFingerprints = new Set<string>()
+
+export const approvalBoundAgent = new Agent({
+  id: 'approval-bound-agent',
+  name: 'Approval Bound Agent',
+  model: 'openai/gpt-5.6-sol',
+  tools: { issueRefundTool, deleteRecordTool },
+  hooks: {
+    beforeToolCall: ({ toolName, input }) => {
+      if (!sensitiveTools.has(toolName)) return
+
+      const fingerprint = actionFingerprint(toolName, input)
+      if (!approvedFingerprints.delete(fingerprint)) {
+        return {
+          proceed: false,
+          output: `Tool call blocked: approval did not match ${toolName} arguments.`,
+        }
+      }
+    },
+  },
+})
+```
+
+```typescript
+const stream = await approvalBoundAgent.stream('Refund order ord-1042', {
+  requireToolApproval: ({ toolName }) => sensitiveTools.has(toolName),
+})
+
+async function consumeApprovalStream(currentStream: typeof stream) {
+  for await (const chunk of currentStream.fullStream) {
+    if (chunk.type === 'tool-call-approval') {
+      const { toolName, toolCallId, args } = chunk.payload
+      const fingerprint = actionFingerprint(toolName, args)
+
+      // Present toolName, args, and fingerprint to your approval UI.
+      const approved = await showApprovalDialog({ toolName, args, fingerprint })
+
+      const nextStream = approved
+        ? await approveReviewedToolCall(currentStream.runId, toolCallId, fingerprint)
+        : await approvalBoundAgent.declineToolCall({ runId: currentStream.runId, toolCallId })
+
+      await consumeApprovalStream(nextStream)
+    }
+  }
+}
+
+async function approveReviewedToolCall(runId: string, toolCallId: string, fingerprint: string) {
+  approvedFingerprints.add(fingerprint)
+  return approvalBoundAgent.approveToolCall({ runId, toolCallId })
+}
+
+await consumeApprovalStream(stream)
+```
+
+In production, store the approved fingerprint in durable storage scoped to the user, run, tool call, and policy version. The `Set` above is intentionally small so the boundary is clear: the approval is consumed once, and only for the same canonical tool arguments that were reviewed.
+
 ### Runtime suspension with `suspend()`
 
 A tool can also pause _during_ its `execute` function by calling `suspend()`. This is useful when the tool starts running and then discovers it needs additional user input or confirmation before it can finish.

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

@@ -210,7 +210,7 @@ Once your agent is running, use this table to find the right page for what you w
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
 | Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/agents/supervisor-agents)       |
 | 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/docs/voice/overview)                         |
+| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/guides/voice/overview)                       |
 | Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels/overview)      |
 
 ## Multi-agent systems

package/.docs/docs/agents/supervisor-agents.md

@@ -420,12 +420,12 @@ const result = await supervisor.generate('Research and write about AI safety', {
 })
 ```
 
-Version overrides propagate automatically through delegation. See [Subagent versioning](https://mastra.ai/docs/editor/overview) for details on resolution order and server API usage.
+Version overrides propagate automatically through delegation. See [Subagent versioning](https://mastra.ai/reference/editor/versioning) for details on resolution order and server API usage.
 
 ## Related
 
 - [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
-- [Subagent versioning](https://mastra.ai/docs/editor/overview)
+- [Subagent versioning](https://mastra.ai/reference/editor/versioning)
 - [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.streamUntilIdle() reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)

package/.docs/docs/agents/using-tools.md

@@ -65,31 +65,6 @@ export const weatherAgent = new Agent({
 })
 ```
 
-## Use provider web search
-
-Import `webSearchTool` from `@mastra/core/tools` when you want the model provider to run its native web search tool. The tool has no local `execute` function. Mastra resolves it at run time from the active model, then passes the provider-managed tool to the model.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { webSearchTool } from '@mastra/core/tools'
-
-export const researchAgent = new Agent({
-  id: 'research-agent',
-  name: 'Research Agent',
-  instructions: `
-    You are a helpful research assistant.
-    Use web search when you need current information.`,
-  model: 'openai/gpt-5.6-sol',
-  tools: {
-    webSearch: webSearchTool,
-  },
-})
-```
-
-`webSearchTool` supports OpenAI, Anthropic, Google Gemini, and xAI models. If Mastra can't infer one of those providers from the active model, the agent run fails with a `MastraError`.
-
-Only the `webSearchTool` value triggers provider web search. Custom tools with the names `webSearch` or `web_search` stay unchanged.
-
 ## Define schemas
 
 You can define the tool's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
@@ -494,14 +469,67 @@ Note that for subagents, you'll see two different identifiers in stream response
 
 Mastra includes agent-agnostic built-in tools in `@mastra/core/tools` that add interactive and organizational capabilities to any agent.
 
-| Tool            | Purpose                                           |
-| --------------- | ------------------------------------------------- |
-| `ask_user`      | Ask the user a question and wait for their answer |
-| `submit_plan`   | Submit a plan file for user approval              |
-| `task_write`    | Create or replace a structured task list          |
-| `task_update`   | Update one tracked task by ID                     |
-| `task_complete` | Mark one tracked task completed                   |
-| `task_check`    | Check task list completion status                 |
+| Tool            | Purpose                                              |
+| --------------- | ---------------------------------------------------- |
+| `ask_user`      | Ask the user a question and wait for their answer    |
+| `submit_plan`   | Submit a plan file for user approval                 |
+| `task_write`    | Create or replace a structured task list             |
+| `task_update`   | Update one tracked task by ID                        |
+| `task_complete` | Mark one tracked task completed                      |
+| `task_check`    | Check task list completion status                    |
+| `webSearchTool` | Run provider-native web search with the active model |
+| `webFetchTool`  | Fetch a web page by URL and return its text content  |
+
+### Use provider web search
+
+Import `webSearchTool` from `@mastra/core/tools` when you want the model provider to run its native web search tool. Mastra resolves it at run time from the active model, then passes the provider-managed tool to the model.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { webSearchTool } from '@mastra/core/tools'
+
+export const researchAgent = new Agent({
+  id: 'research-agent',
+  name: 'Research Agent',
+  instructions: 'Use web search when you need current information.',
+  model: 'openai/gpt-5.6-sol',
+  tools: {
+    search: webSearchTool,
+  },
+})
+```
+
+`webSearchTool` supports OpenAI, Anthropic, Google Gemini, and xAI models. If Mastra can't infer one of those providers from the active model, the agent run fails with a `MastraError`.
+
+The `search` key is only the agent-local tool name. Use any key. The `webSearchTool` value tells Mastra to use provider web search.
+
+### Fetch a web page
+
+Import `webFetchTool` from `@mastra/core/tools` when the agent needs to read a specific URL. The tool requests the page over HTTP or HTTPS and returns its text content plus response metadata.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { webFetchTool } from '@mastra/core/tools'
+
+export const readerAgent = new Agent({
+  id: 'reader-agent',
+  name: 'Reader Agent',
+  instructions: 'Fetch the page the user links to before answering.',
+  model: 'openai/gpt-5.6-sol',
+  tools: {
+    fetch: webFetchTool,
+  },
+})
+```
+
+The tool takes a single `url` input and returns `content`, `truncated`, `status`, `statusText`, `contentType`, `url`, and `ok`. It applies these limits:
+
+- Only `http:` and `https:` URLs are allowed.
+- Requests to `localhost` and to private or reserved IP addresses are blocked, including addresses returned by DNS resolution.
+- Responses are truncated at 100,000 characters, with `truncated: true` in the result.
+- Requests follow at most 5 redirects and time out after 15 seconds.
+
+Failures don't throw. The tool returns `isError: true` with the reason in `content`, so the agent can retry or explain the problem.
 
 ### Ask the user a question
 

package/.docs/docs/{evals/datasets → datasets}/overview.md

@@ -49,7 +49,7 @@ Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/dat
 
 You can also manage datasets in [Studio](https://mastra.ai/docs/studio/overview). After opening Studio, select **Datasets** from the sidebar to see all your available datasets or create a new one.
 
-To get started, select **Create Dataset** and set a name, description, and optional schemas. After confirming, you'll see the dataset details page with two tabs: **Items** and [**Experiments**](https://mastra.ai/docs/evals/datasets/running-experiments).
+To get started, select **Create Dataset** and set a name, description, and optional schemas. After confirming, you'll see the dataset details page with two tabs: **Items** and [**Experiments**](https://mastra.ai/docs/datasets/running-experiments).
 
 In the **Items** view you can add, update, and delete items, and view version history. Select **Add Item** to insert a new item with JSON editors for input and ground truth. From this view you can also import items in bulk from a CSV or JSON file. When importing, map each column to the corresponding dataset field.
 
@@ -198,11 +198,11 @@ Fetch the exact items that existed at a past version:
 const items = await dataset.listItems({ version: 2 })
 ```
 
-You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
+You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/datasets/running-experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
 
 ## Related
 
-- [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
+- [Running experiments](https://mastra.ai/docs/datasets/running-experiments)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [DatasetsManager reference](https://mastra.ai/reference/datasets/datasets-manager)
 - [Dataset reference](https://mastra.ai/reference/datasets/dataset)

package/.docs/docs/{evals/datasets → datasets}/running-experiments.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-An experiment runs every item in a dataset through a target (an agent, a workflow, or a scorer) and then optionally scores the outputs. Use a scorer as the target when you want to evaluate an LLM judge itself. Results are persisted to storage so you can compare runs across different prompts, models, or code changes.
+An experiment runs every item in a dataset through a target (an agent, a workflow, or a scorer) and then optionally scores the outputs. Use a scorer as the target when you want to evaluate an LLM judge itself. By default, results are persisted to storage so you can compare runs across different prompts, models, or code changes.
 
 **For AI agents:** Run `npx mastra api experiment run dataset_123 '{"name":"translation-baseline"}'` to start an experiment directly instead of opening Studio or writing a temporary script. Use a dataset ID returned by `npx mastra api dataset list` in place of the sample ID. The command requires a running Mastra server with dataset storage and registered experiment targets; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api experiment run --schema` before constructing different input, and get user approval before starting an experiment because it can make model calls. 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.
 
@@ -131,9 +131,33 @@ for (const item of summary.results) {
 
 Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
+## Control persistence per run
+
+Use `persistence` to skip storage writes for a specific run. Experiment records and score records can be disabled independently:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'translation-agent',
+  scorers: ['accuracy'],
+  persistence: {
+    experiments: 'none',
+    scores: 'none',
+  },
+})
+```
+
+The target and scorers still run, and `startExperiment()` still returns the item results and scores in `summary`. The settings are independent. For example, set only `scores: 'none'` to persist the experiment and its item results without creating score records.
+
+Omitted settings default to `'default'`, which preserves the standard storage behavior. This policy only controls experiment and score records created by the run. It doesn't disable storage used by the target, such as agent memory, vectors, observability, or custom tool storage.
+
+When `startExperimentAsync()` runs with `experiments: 'none'`, it doesn't persist an experiment record, progress updates, or item results. Score persistence remains controlled separately by `persistence.scores`. Without an experiment event observer, the run is fire-and-forget, and the experiment API can't report whether it completed or failed.
+
+Use synchronous `startExperiment()` when the caller needs the returned summary. An experiment event observer can receive lifecycle events and the terminal summary.
+
 ## Tool mocks
 
-When an experiment runs an agent that calls side-effecting tools, you can make the run deterministic by attaching static tool mocks to individual dataset items. During the experiment, a mocked tool returns its declared output instead of executing. Tools that have no mock on the item run live.
+When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.
 
 Mocks live on the dataset item, so they version with the row and travel with the test case. Each mock declares a tool name, the arguments it expects, and the output to return:
 
@@ -152,6 +176,29 @@ await dataset.addItem({
 
 Tool mocks are supported for `agent` targets only.
 
+### Block undeclared tools
+
+Set `unmockedToolPolicy: 'deny'` on an experiment to block every tool call that doesn't have a mock. This is useful when a live call could cause side effects:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'weather-agent',
+  unmockedToolPolicy: 'deny',
+})
+```
+
+The default policy is `'allow'`. You can override the experiment policy on an individual stored or inline item:
+
+```typescript
+await dataset.addItem({
+  input: 'What is the weather in Seattle?',
+  unmockedToolPolicy: 'allow',
+})
+```
+
+The item value takes precedence over the experiment value. A denied call fails with `TOOL_MOCK_NOT_DECLARED` before the tool executes. The failure isn't retried or added to `liveCalls`.
+
 ### Matching and consumption
 
 Arguments are matched strictly: object key order is ignored and array order is substantial, plus there is no type coercion. A mock is served only when the agent calls the tool with arguments that deep-equal the mock's `args`.
@@ -175,14 +222,15 @@ This is useful when a tool's arguments are noisy or generated by the model. The
 
 ### Failures
 
-A mocked tool call fails the item when the arguments don't match or all matching mocks have been consumed:
+A tool call fails the item when it violates the mock configuration:
 
 - `TOOL_MOCK_MISMATCH`: the tool was called with arguments that no mock matches.
 - `TOOL_MOCK_EXHAUSTED`: every matching mock has already been consumed.
+- `TOOL_MOCK_NOT_DECLARED`: the tool has no mock and the effective `unmockedToolPolicy` is `'deny'`.
 
-When a mocked tool is mis-called, the agent run is aborted immediately, so the model can't go on to call any further tools, including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they're not retried. Mocks that are declared but never used don't fail the item, they're reported as unconsumed.
+On any of these failures, the agent run is aborted immediately, so the model can't go on to call any further tools, including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they're not retried. Mocks that are declared but never used don't fail the item, they're reported as unconsumed.
 
-While an item has mocks, the agent's tools execute sequentially so repeated `(toolName, args)` mocks are consumed in the provider's call order. This serialization applies only to items that declare mocks.
+While mock interception is active, the agent's tools execute sequentially so repeated `(toolName, args)` mocks are consumed in the provider's call order. Interception is active when the item declares mocks or its effective `unmockedToolPolicy` is `'deny'`.
 
 ### Diagnostics
 
@@ -195,8 +243,8 @@ for (const item of summary.results) {
 
   console.log(report.served) // mocks matched and returned
   console.log(report.unconsumed) // mocks declared but never used
-  console.log(report.liveCalls) // unmocked tools that ran live
-  console.log(report.failure) // the mismatch/exhausted failure, if any
+  console.log(report.liveCalls) // undeclared tools allowed to run live
+  console.log(report.failure) // the first deterministic mock failure, if any
 }
 ```
 
@@ -205,7 +253,7 @@ In [Studio](https://mastra.ai/docs/studio/overview), edit a dataset item to auth
 ### Limitations
 
 - **No tool span for mocked calls.** A mocked call returns its output before the tool executes, so it doesn't create a tool span. Trajectory scorers backed by stored traces may therefore not see mocked tool calls. Trajectory extraction that falls back to the agent's message output still sees them, so trajectory scoring can differ depending on your observability configuration.
-- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter doesn't support them and rejects writes that carry tool mocks or a tool mock report so the feature never silently runs tools live.
+- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter doesn't support them and rejects writes that carry tool mocks or a tool mock report. All dataset storage adapters persist `unmockedToolPolicy`.
 
 ## Async experiments
 
@@ -350,7 +398,7 @@ Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/sta
 
 ## Related
 
-- [Datasets overview](https://mastra.ai/docs/evals/datasets/overview)
+- [Datasets overview](https://mastra.ai/docs/datasets/overview)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment)
 - [`listExperimentResults` reference](https://mastra.ai/reference/datasets/listExperimentResults)

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

@@ -17,7 +17,7 @@ Workers matter when any of these apply:
 - Different parts of the system need to scale independently (e.g., more orchestration capacity without more API instances)
 - Background tool calls should run on dedicated compute
 
-If your application handles light traffic and workflows complete quickly, the default in-process setup works fine. Skip the worker infrastructure until you need it.
+If your application handles light traffic and workflows complete fast, the default in-process setup works fine. Skip the worker infrastructure until you need it.
 
 ## Worker types
 
@@ -33,11 +33,11 @@ The orchestration worker requires a PubSub backend that supports pull mode (e.g.
 
 ### Scheduler worker
 
-Polls storage for due cron schedules and publishes `workflow.start` events. It is a producer only, meaning it creates work for the orchestration worker to pick up.
+Polls storage for due cron schedules and publishes `workflow.start` events. It's a producer only, meaning it creates work for the orchestration worker to pick up.
 
 The scheduler reads declarative `schedule` fields from your workflow definitions automatically. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for how to declare schedules.
 
-**Do not run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
+**Don't run more than one scheduler instance.** Multiple schedulers polling the same storage would fire duplicate events for the same schedule.
 
 ### Background task worker
 
@@ -47,7 +47,7 @@ The background task worker manages concurrency limits, task lifecycle, and resul
 
 ## How workers run
 
-### In-process (default)
+### In-process mode (default)
 
 With no configuration, Mastra creates and starts workers inside the API process. Events flow through an in-memory PubSub, and everything shares a single Node.js runtime.
 
@@ -64,7 +64,7 @@ This setup needs no external infrastructure beyond your storage adapter. It does
 
 ### Split processes
 
-To run workers separately, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
+To run workers in their own processes, configure a distributed [PubSub](https://mastra.ai/docs/server/pubsub) backend and use the `MASTRA_WORKERS` environment variable to control which workers start in each process.
 
 **Redis Streams + PostgreSQL**:
 
@@ -100,38 +100,38 @@ export const mastra = new Mastra({
 })
 ```
 
-Any [supported storage backend](https://mastra.ai/reference/workers/overview) works — swap the storage adapter for your preferred database.
+Any [supported storage backend](https://mastra.ai/reference/workers/overview) works. Swap the storage adapter for your preferred database.
 
 Run the same build artifact in multiple containers, each with a different [`MASTRA_WORKERS`](https://mastra.ai/reference/workers/overview) value to control which worker starts in each process.
 
 Split deployments require a distributed PubSub backend ([`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)), a shared [storage backend](https://mastra.ai/reference/workers/overview), and network connectivity between the orchestration worker and the API.
 
-The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with a Docker Compose example.
+The [worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers) walks through this setup with Docker Compose and Kubernetes examples.
 
 ## Network architecture
 
-Workers are internal infrastructure. They are not exposed to end users and do not need their own subdomain, public URL, or inbound HTTP route.
+Workers are internal infrastructure. They're not exposed to end users and don't need their own subdomain, public URL, or inbound HTTP route.
 
 In a split deployment:
 
-- **The API server is the only public-facing process.** It serves all client HTTP requests — REST endpoints, agent interactions, workflow triggers, and any custom routes.
-- **Workers connect outbound only.** They pull events from the distributed PubSub backend and read/write to the shared storage database. They do not accept inbound traffic from clients.
-- **The orchestration worker calls the API internally.** It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
+- **The API server is the only public-facing process**: It serves all client HTTP requests, including REST endpoints, agent interactions, workflow triggers, and any custom routes.
+- **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
+- **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
 All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. If a worker-related feature needs an HTTP route (for example, token minting for a voice integration), that route runs on the API server, not on the worker process.
 
 ## Known limitations
 
-- **No dead-letter queue**: Failed events are nacked and retried, but there is no DLQ for events that repeatedly fail.
+- **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.
 
 ## Related
 
-- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose example and topology options
+- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Docker Compose and Kubernetes examples
 - [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
-- [Workers reference](https://mastra.ai/reference/workers/overview): Environment variables, worker types, and storage backends
+- [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
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): Declare cron schedules on workflows