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

package/.docs/reference/memory/observational-memory.md

@@ -27,7 +27,7 @@ export const agent = new Agent({
 
 ## Configuration
 
-The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, a `model` must be explicitly set: either at the top level or on `observation.model` and/or `reflection.model`.
+The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, set `model` at the top level or on `observation.model` and/or `reflection.model`; when all model fields are omitted, OM falls back to `google/gemini-2.5-flash`.
 
 Observer input is multimodal-aware. OM keeps text placeholders like `[Image #1: screenshot.png]` in the transcript it builds for the Observer, and also sends the underlying image parts when possible. This applies to both single-thread observation and batched multi-thread observation. Non-image files appear as placeholders only.
 
@@ -35,7 +35,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **enabled** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to true. Only enabled: false explicitly disables it. (Default: `true`)
 
-**model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with observation.model or reflection.model — an error will be thrown if both are set. When using observationalMemory: true, defaults to google/gemini-2.5-flash. When passing a config object, this or observation.model/reflection.model must be set. Use "default" to explicitly use the default model (google/gemini-2.5-flash). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
+**model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with observation.model or reflection.model — an error will be thrown if both are set. When this and observation.model/reflection.model are all omitted, OM falls back to google/gemini-2.5-flash. Use "default" to explicitly use the default model (google/gemini-2.5-flash). (Default: `'google/gemini-2.5-flash'`)
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. 'thread' keeps observations per-thread. 'resource' (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
@@ -47,7 +47,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **temporalMarkers** (`boolean`): Insert temporal-gap reminder markers before new user messages when the previous message in the thread is at least 10 minutes older. The marker is persisted in memory, emitted as an inline reminder event so clients can render it specially, and shown to the observer so it can anchor observations to when events occurred. (Default: `false`)
 
-**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Enable retrieval-mode observation groups as durable pointers to raw message history. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource'; instructions?: string }`): Let the agent look up the raw message history behind its observations. Observation groups keep durable pointers to the original messages, and a recall tool is registered so the agent can browse them. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. { instructions: '...' } appends application-specific recall guidance after Mastra's built-in retrieval instructions. (Default: `false`)
+
+**hooks** (`ObserveHooks`): Lifecycle hooks fired for every observation/reflection cycle — the manual observe()/reflect() APIs, turn-driven synchronous observation, and fire-and-forget async buffering. Callbacks receive threadId/resourceId/trigger call context ('manual' | 'turn-sync' | 'async-buffer'), and the end hooks (onObservationEnd/onReflectionEnd) additionally receive the OM model call's token usage and providerMetadata (where providers such as the AI Gateway report per-call cost), so apps can account for OM model spend without wrapping the observer/reflector models in middleware. Failed async-buffered cycles never throw; they report through the end hook's error field. Errors thrown by these hooks are caught and logged — they never fail the cycle.
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -59,29 +61,33 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.extract** (`Extractor[]`): Custom values to extract after observation. Schema-less extractors are requested inline in the Observer output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
 
-**observation.observeAttachments** (`boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. true (default) forwards all attachments. false drops all attachments while keeping placeholders visible. An array is a case-insensitive mimeType allowlist supporting exact matches ('application/pdf'), wildcard subtypes ('image/\*'), and bare '\*' for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
+**observation.manageWorkingMemory** (`boolean`): Let the Observer manage working memory through OM extraction. Adds WorkingMemoryExtractor, defaults workingMemory.agentManaged to false, and defaults workingMemory.useStateSignals to true. See Working memory updates.
+
+**observation.observeAttachments** (`'auto' | boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. true (default) forwards all attachments. false drops all attachments while keeping placeholders visible. 'auto' uses the provider capabilities registry to decide: attachments are forwarded when the Observer model supports multimodal input, dropped otherwise, and forwarded when no capability data is available for the model. An array is a case-insensitive mimeType allowlist supporting exact matches ('application/pdf'), wildcard subtypes ('image/\*'), and bare '\*' for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
 
 **observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with tokenx. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like file parts are counted the same way when uploads are normalized as files.
 
 **observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
 
-**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent.
+**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
 **observation.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
 
-**observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
+**observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations. The 100000 default is only applied with default model selection; custom models get no default.
 
-**observation.bufferTokens** (`number | false`): Token interval for async background observation buffering. Can be an absolute token count (e.g. 5000) or a fraction of messageTokens (e.g. 0.25 = buffer every 25% of threshold). When set, observations run in the background at this interval, storing results in a buffer. When the main messageTokens threshold is reached, buffered observations activate instantly without a blocking LLM call. Must resolve to less than messageTokens. Set to false to explicitly disable all async buffering (both observation and reflection).
+**observation.providerOptions** (`ProviderOptions`): Provider-specific options passed to the Observer agent, such as Google thinking configuration.
+
+**observation.bufferTokens** (`number | false`): How often background observation buffering runs. Values between 0 and 1 are fractions of messageTokens: 0.25 buffers every 25% of the threshold (7.5k tokens with the default 30k). Values of 1 or more are absolute token counts: 5000 buffers every 5k tokens. Buffered observations are stored until the messageTokens threshold is reached, then activate instantly without a blocking LLM call. Must resolve to less than messageTokens. Set to false to disable all async buffering (both observation and reflection).
 
 **observation.bufferOnIdle** (`boolean`): Run background observation buffering when an agent turn ends and the agent becomes idle. This is separate from bufferTokens, which controls step-time async buffering. Set this to true to buffer short idle turns without waiting for the next turn or the messageTokens threshold.
 
-**observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, 0.8 means: activate enough buffers to remove 80% of messageTokens and leave 20% as active message history. An absolute token count like 4000 targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
+**observation.bufferActivation** (`number`): How much of the message window to clear when buffered observations activate. Values between 0 and 1 are the fraction of messageTokens to remove: 0.8 removes \~80% of the message history and keeps \~20% (6k tokens with the default 30k). Values of 1000 or more are the token count to keep: 4000 keeps \~4k message tokens after activation. Note the direction flips: a higher ratio removes more history, while a higher token count keeps more.
 
-**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations.
+**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateAfterIdle only.
 
-**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations.
+**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.
 
-**observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between messageTokens and blockAfter, only async buffering/activation is used. Above blockAfter, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by messageTokens) or an absolute token count (≥ 2, must be greater than messageTokens). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
+**observation.blockAfter** (`number`): Safety net that forces a synchronous (blocking) observation when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 forces a blocking observation at 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Between messageTokens and blockAfter, only async buffering and activation run; buffered activation still preserves a minimum remaining context (the smaller of 1000 tokens or the retention floor). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to 0 to omit previous observations entirely, or false to disable truncation explicitly.
 
@@ -95,19 +101,21 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.observationTokens** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them.
 
-**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent.
+**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
 **reflection.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
 
-**reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
+**reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations. The 100000 default is only applied with default model selection; custom models get no default.
+
+**reflection.providerOptions** (`ProviderOptions`): Provider-specific options passed to the Reflector agent, such as Google thinking configuration.
 
-**reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach observationTokens \* bufferActivation, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
+**reflection.bufferActivation** (`number`): When background reflection starts, as a ratio (0-1) of observationTokens: 0.5 starts reflecting in the background once observations reach 50% of the threshold (20k tokens with the default 40k). When the full threshold is reached, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
-**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. Reflections do not inherit top-level activateAfterIdle; set this explicitly to opt reflections into idle activation.
+**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. Reflections do not inherit top-level activateAfterIdle; set this explicitly to opt reflections into idle activation. Currently only applied when using the standalone ObservationalMemory class; this setting has no effect through new Memory(...).
 
-**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level activateOnProviderChange; set this explicitly to opt reflections into provider-change activation.
+**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level activateOnProviderChange; set this explicitly to opt reflections into provider-change activation. Currently only applied when using the standalone ObservationalMemory class; this setting has no effect through new Memory(...).
 
-**reflection.blockAfter** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between observationTokens and blockAfter, only async buffering/activation is used. Above blockAfter, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by observationTokens) or an absolute token count (≥ 2, must be greater than observationTokens). Only relevant when bufferActivation is set. Defaults to 1.2 when async reflection is enabled.
+**reflection.blockAfter** (`number`): Safety net that forces a synchronous (blocking) reflection when background reflection can't keep up. Values from 1 up to (but not including) 100 are multipliers of observationTokens: 1.2 forces a blocking reflection at 120% of the threshold (48k tokens with the default 40k). Values of 100 or more are absolute token counts and must be greater than observationTokens. Between observationTokens and blockAfter, only async buffering and activation run. Only relevant when bufferActivation is set. Defaults to 1.2 when async reflection is enabled.
 
 ### Token estimate metadata cache
 
@@ -150,7 +158,7 @@ const memory = new Memory({
 
 **name** (`string`): Human-readable extractor name. OM slugifies this value into the extractor slug. Names must be unique after slug generation.
 
-**slug** (`string`): Generated stable identifier for persisted values and XML tags. Slugs use lowercase letters, numbers, and hyphens. Built-in slugs and reserved XML tags cannot be used by custom extractors.
+**slug** (`string`): Read-only property derived from name — not a constructor option. Generated stable identifier for persisted values and XML tags. Slugs use lowercase letters, numbers, and hyphens. Built-in slugs and reserved XML tags cannot be used by custom extractors.
 
 **instructions** (`string | (context) => string`): Instructions for what to extract and when to update the value. Use a function to derive instructions from runtime context.
 
@@ -158,6 +166,8 @@ const memory = new Memory({
 
 **includePreviousExtraction** (`boolean`): Controls whether the previous extraction is shown to the extractor on future OM runs. Set to false for values that should only come from the current OM run. (Default: `true`)
 
+**metadataKeyPath** (`string | false`): Dot-separated OM metadata path used to persist the extracted value. Set to false to skip OM metadata persistence entirely. (Default: `'extracted.<slug>'`)
+
 **onExtracted** (`(context) => T | void | Promise<T | void>`): Optional hook called after a custom extractor returns a value and before metadata is persisted. Returning a value replaces the extracted value. Throwing records an extraction failure.
 
 ### Extraction behavior
@@ -663,18 +673,45 @@ Emitted when buffered observations or reflections are activated (moved into the
 
 **observations** (`string`): The activated observations text.
 
+**triggeredBy** (`'threshold' | 'ttl' | 'provider_change'`): Whether activation was triggered by threshold crossing, activateAfterIdle expiry, or a model/provider change.
+
+**lastActivityAt** (`number`): Unix-ms timestamp of the last assistant message part used for TTL checks.
+
+**ttlExpiredMs** (`number`): How long activateAfterIdle had been exceeded when activation fired.
+
+**previousModel** (`string`): Previous assistant model identifier that triggered activation (e.g. openai/gpt-4o).
+
+**currentModel** (`string`): Current actor model identifier that triggered activation.
+
 **recordId** (`string`): The OM record ID.
 
 **threadId** (`string`): This thread's ID.
 
 **config** (`ObservationMarkerConfig`): Snapshot of config at activation time.
 
+### `data-om-thread-update`
+
+Emitted when the Observer updates the thread title. Only emitted when `observation.threadTitle` is enabled.
+
+**cycleId** (`string`): Unique ID for this observation cycle — shared with observation markers.
+
+**threadId** (`string`): The thread ID that was updated.
+
+**oldTitle** (`string`): The previous thread title. Undefined if the thread had no title.
+
+**newTitle** (`string`): The new thread title.
+
+**timestamp** (`string`): When this update occurred.
+
 ## Standalone usage
 
 Most users should use the `Memory` class above. Using `ObservationalMemory` directly is mainly useful for benchmarking, experimentation, or when you need to control processor ordering with other processors (like [guardrails](https://mastra.ai/docs/agents/guardrails)).
 
+The `ObservationalMemory` class is the engine; to attach it to an agent, wrap it in an `ObservationalMemoryProcessor`, which needs a `Memory` instance for loading and persisting messages. Note that `stores.memory` is typed as optional on storage adapters, so a non-null assertion (or a runtime check) is needed:
+
 ```typescript
-import { ObservationalMemory } from '@mastra/memory/processors'
+import { ObservationalMemory, ObservationalMemoryProcessor } from '@mastra/memory/processors'
+import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 import { LibSQLStore } from '@mastra/libsql'
 
@@ -683,8 +720,11 @@ const storage = new LibSQLStore({
   url: 'file:./memory.db',
 })
 
+const memory = new Memory({ storage })
+
 const om = new ObservationalMemory({
-  storage: storage.stores.memory,
+  storage: storage.stores.memory!,
+  memory,
   model: 'google/gemini-2.5-flash',
   scope: 'resource',
   observation: {
@@ -695,13 +735,15 @@ const om = new ObservationalMemory({
   },
 })
 
+const omProcessor = new ObservationalMemoryProcessor(om, memory)
+
 export const agent = new Agent({
   id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
-  inputProcessors: [om],
-  outputProcessors: [om],
+  inputProcessors: [omProcessor],
+  outputProcessors: [omProcessor],
 })
 ```
 
@@ -719,15 +761,19 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list.
 
+Mastra also injects scope-aware usage instructions into the agent's context. For resource scope with `vector: true`, these cover routing between `search`, `threads`, and `messages`, including fallback to thread discovery when search results are unsuitable. Without `vector: true`, the instructions only cover `threads` and `messages` browsing, so the agent isn't steered toward a search mode that isn't configured. Resource-scoped instructions are injected even before any observation group exists, so the agent can browse other threads from the first message. Use `retrieval: { instructions: '...' }` to append application-specific guidance after the built-in instructions.
+
 ### Parameters
 
 **mode** (`'messages' | 'threads' | 'search'`): What to retrieve. "messages" (default) pages through message history. "threads" lists all threads for the current user. "search" finds messages by semantic similarity across all threads (requires vector store and embedder). (Default: `'messages'`)
 
 **query** (`string`): Search query for mode: "search". Finds messages semantically similar to this text across all threads for the current user.
 
-**cursor** (`string`): A message ID to anchor the recall query. Required for mode: "messages" when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \_range: \startId:endId\\\_, use either startId or endId). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. Can be omitted when threadId is provided to start reading from the beginning of that thread.
+**cursor** (`string`): A message ID to anchor the recall query. Extract the start or end ID from an observation group range (e.g. from \_range: \startId:endId\\\_, use either startId or endId). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. When both cursor and threadId are omitted for mode: "messages", the tool browses the current thread from the position set by anchor.
+
+**threadId** (`string`): Browse a different thread by its ID, or pass "current" for the active thread. Use mode: "threads" first to discover thread IDs. When provided without a cursor, reading starts from the beginning of the thread.
 
-**threadId** (`string`): Browse a different thread by its ID. Use mode: "threads" first to discover thread IDs. When provided without a cursor, reading starts from the beginning of the thread.
+**anchor** (`'start' | 'end'`): For mode: "messages" without a cursor, page from the start (oldest-first) or end (newest-first) of the thread. (Default: `'start'`)
 
 **page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). 0 is treated as 1 for messages. (Default: `1`)
 
@@ -735,6 +781,10 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 **detail** (`'low' | 'high'`): Controls how much content is shown per message part. 'low' shows truncated text and tool names with positional indices (\[p0], \[p1]). 'high' shows full content including tool arguments and results, clamped to one part per call with continuation hints. (Default: `'low'`)
 
+**partType** (`'text' | 'tool-call' | 'tool-result' | 'reasoning' | 'image' | 'file'`): Filter results to only include message parts of this type. Only applies to mode: "messages".
+
+**toolName** (`string`): Filter results to only include tool-call and tool-result parts matching this tool name. Only applies to mode: "messages".
+
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \[p1] — call again with partIndex: 1 to see the full content without loading every part.
 
 **before** (`string`): For mode: "threads" only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. "2026-03-15", "2026-03-10T00:00:00Z").
@@ -753,6 +803,8 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 **limit** (`number`): The limit used for this query.
 
+**detail** (`'low' | 'high'`): The detail level used for this query.
+
 **hasNextPage** (`boolean`): Whether more messages exist after this page.
 
 **hasPrevPage** (`boolean`): Whether more messages exist before this page.

package/.docs/reference/memory/serialized-memory-config.md

@@ -4,7 +4,7 @@
 
 `SerializedMemoryConfig` is the JSON-serializable subset of [`Memory`](https://mastra.ai/reference/memory/memory-class) configuration that lives on a stored agent record. The runtime hydrates it back into a `Memory` instance by resolving the vector and embedder IDs against the configured `Mastra` instance.
 
-It's the type used by [`BuilderAgentDefaults.memory`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by `EditorAgentNamespace.create({ memory })`.
+It's the type used by [`BuilderAgentDefaults.memory`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) and by `EditorAgentNamespace.create({ memory })`.
 
 ## Usage example
 
@@ -70,5 +70,5 @@ new MastraEditor({
 
 - [Memory class](https://mastra.ai/reference/memory/memory-class): The runtime type this config hydrates into.
 - [Observational memory](https://mastra.ai/reference/memory/observational-memory): Full observational memory reference.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Where this type is pinned as the Builder default.
-- [Agent Builder: Memory](https://mastra.ai/docs/agent-builder/memory): Concept and worked examples.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Where this type is pinned as the Builder default.
+- [Agent Builder: Memory](https://agent-builder.mastra.ai/memory): Concept and worked examples.

package/.docs/reference/observability/tracing/interfaces.md

@@ -319,7 +319,9 @@ enum SpanType {
    * Provider-executed (server-side) tool span. Reconstructed from
    * tool-call and tool-result stream chunks for tools the model
    * provider executes (e.g. Anthropic code execution, server-side
-   * web search). Opened on tool-call chunk, closed on tool-result.
+   * web search). Created on the tool-result chunk under the model
+   * step that delivered it, with the start time backdated to the
+   * tool-call chunk.
    */
   PROVIDER_TOOL_CALL = 'provider_tool_call',
 
@@ -473,6 +475,7 @@ interface ToolCallAttributes {
   toolId?: string
   toolType?: string
   toolDescription?: string
+  toolCallId?: string
   success?: boolean
 }
 ```
@@ -495,6 +498,8 @@ interface MCPToolCallAttributes {
   /** Tool description */
   toolDescription?: string
 
+  toolCallId?: string
+
   /** Whether tool execution was successful */
   success?: boolean
 }

package/.docs/reference/processors/processor-interface.md

@@ -399,7 +399,7 @@ processLLMRequest?(
 
 **tracingContext** (`TracingContext`): Tracing context for observability.
 
-**writer** (`ProcessorStreamWriter`): Stream writer for emitting custom data chunks during streaming. Use writer.custom() to send transient UI signals.
+**writer** (`ProcessorStreamWriter`): Stream writer for emitting custom data chunks during streaming. Call writer.custom() to emit a data-\* chunk.
 
 **abortSignal** (`AbortSignal`): Signal for cancelling the operation.
 
@@ -504,7 +504,7 @@ processAPIError?(args: ProcessAPIErrorArgs): Promise<ProcessAPIErrorResult | voi
 
 **abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing.
 
-**writer** (`ProcessorStreamWriter`): Stream writer for emitting custom data chunks during streaming. Use writer.custom() to send transient UI signals.
+**writer** (`ProcessorStreamWriter`): Stream writer for emitting custom data chunks during streaming. Call writer.custom() to emit a data-\* chunk.
 
 **requestContext** (`RequestContext`): Request context passed through from the agent call.
 
@@ -961,6 +961,18 @@ await writer.custom({
 })
 ```
 
+When memory is configured, custom `data-*` chunks emitted from `processOutputStream` or `processOutputResult` are saved as parts of the assistant message. Set `transient: true` on the chunk object to stream it without saving it to memory:
+
+```typescript
+await writer.custom({
+  type: 'data-progress',
+  data: { status: 'Processing' },
+  transient: true,
+})
+```
+
+Pass `transient` as a property of the chunk, not as the second argument to `writer.custom()`. The second argument contains writer options such as `messageId`.
+
 By default, processors **don't** see `data-*` chunks in `processOutputStream` so they don't accidentally process tool telemetry or their own output. Opt in by setting `processDataParts: true` on the processor:
 
 ```typescript

package/.docs/reference/processors/regex-filter-processor.md

@@ -125,7 +125,7 @@ A replacement string can reference capture groups with `$1` or `$&`. Those refer
 
 ## Redaction reporting
 
-The `redact` strategy rewrites text in place, so nothing downstream can tell what changed. Assign `onViolation` to record it. The processor calls it once per redacted message, message part, or stream chunk, and offsets are relative to that piece of text. Async callbacks are awaited, and errors are caught so an unavailable audit sink cannot fail the request.
+The `redact` strategy rewrites text in place, so nothing downstream can tell what changed. Assign `onViolation` to record it. The processor calls it once per redacted message, message part, or stream chunk, and offsets are relative to that piece of text. Async callbacks are awaited, and errors are caught so an unavailable audit sink can't fail the request.
 
 ```typescript
 import { RegexFilterProcessor, type RegexRedactionDetail } from '@mastra/core/processors'

package/.docs/reference/processors/token-limiter-processor.md

@@ -44,12 +44,26 @@ const processor = new TokenLimiterProcessor({
 
 **processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Prunes messages at each step of the agentic loop (including tool call continuations) to keep the conversation within the token limit. Mutates the messageList directly by removing oldest messages first while preserving system messages.
 
-**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming
+**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming. Only text and object parts count against the limit and can be withheld; lifecycle, reasoning and tool parts always pass through.
 
 **processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to limit token count in non-streaming scenarios
 
 **getMaxTokens** (`() => number`): Get the maximum token limit
 
+## Output stream behavior
+
+As an output processor, only parts that carry generated output count against the limit: `text-delta` and `object`. Lifecycle parts (such as `step-start`), reasoning deltas, response metadata, and tool parts (`tool-call`, `tool-result`) are neither counted nor withheld, so tool calls always reach the agentic loop and get executed.
+
+With the default `truncate` strategy, the first time output is withheld the processor emits a transient `data-token-limit-reached` part on the stream:
+
+```typescript
+for await (const part of stream.fullStream) {
+  if (part.type === 'data-token-limit-reached') {
+    console.log('output truncated at', part.data.limit, 'tokens')
+  }
+}
+```
+
 ## Error behavior
 
 When used as an input processor (both `processInput` and `processInputStep`), `TokenLimiterProcessor` throws a `TripWire` error in the following cases:

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/file-based-agents) docs.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/develop) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files

package/.docs/reference/rag/database-config.md

@@ -275,5 +275,5 @@ const vectorTool = createVectorQueryTool({
 ## Related
 
 - [createVectorQueryTool()](https://mastra.ai/reference/tools/vector-query-tool)
-- [Hybrid Vector Search](https://mastra.ai/docs/rag/retrieval)
+- [Hybrid Vector Search](https://mastra.ai/guides/rag/retrieval)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/reference/storage/composite.md

@@ -188,6 +188,8 @@ export const mastra = new Mastra({
 
 **default** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in domains will use this storage's domains as fallbacks.
 
+**editor** (`MastraCompositeStore`): Storage adapter for Editor-owned domains, including agents, prompt blocks, scorers, MCP clients and servers, workspaces, and skills. Takes precedence over default storage but not explicit domain overrides.
+
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
 **domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.

package/.docs/reference/streaming/agents/stream.md

@@ -214,7 +214,7 @@ const stream = await agent.stream('message for agent')
 
 **options.tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
 
-**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See Sub-agent versioning.
+**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See Editor versioning.
 
 **options.versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors.
 

package/.docs/reference/tools/isolated-vm-transport.md

@@ -34,7 +34,7 @@ yarn add @mastra/isolated-vm
 bun add @mastra/isolated-vm
 ```
 
-`isolated-vm` is a native addon. It ships prebuilt binaries for common platforms, so installation usually needs no extra setup. A C++ toolchain is only needed on platforms without a matching prebuild, where it falls back to compiling from source.
+`isolated-vm` is a native addon. It provides prebuilt binaries for common platforms, so installation usually needs no extra setup. A C++ toolchain is only needed on platforms without a matching prebuild, where it falls back to compiling from source.
 
 On Node.js 20 and later, the host process must be started with the `--no-node-snapshot` flag, otherwise creating an isolate crashes the process. The constructor throws an error when the flag is missing. Pass the flag when starting your server, or set it through `NODE_OPTIONS`:
 

package/.docs/reference/vectors/mongodb.md

@@ -109,7 +109,7 @@ Waits for an index to become ready after creation. Useful when you need to ensur
 
 ### `upsert()`
 
-Adds or updates vectors and their metadata in the collection. On a bring-your-own index this requires `allowWrites: true` at `createIndex()` time — BYO collections are read-only by default.
+Adds or updates vectors and their metadata in the collection. On a bring-your-own index, this requires `allowWrites: true` at `createIndex()` time because BYO collections are read-only by default.
 
 **indexName** (`string`): Name of the collection to insert into
 
@@ -148,12 +148,12 @@ Provisions an Atlas Search (BM25/full-text) index on the collection backing an i
 **Managed vs. bring-your-own collections:**
 
 - For a **managed** index (created without `collectionName`), `createIndex()` already provisions a _dynamic_ full-text index named `${collectionName}_search_index` (covering all string fields). `createSearchIndex()` is therefore only needed when you want a **field-restricted** mapping or a **custom index name**.
-- For a **bring-your-own** index (created with `collectionName`), `createIndex()` does **not** auto-create any full-text index — enabling `textQuery()`/`hybridQuery()` on a caller-owned operational collection is **opt-in**. Call `createSearchIndex()` explicitly to provision the (billable) text index; until you do, `textQuery()`/`hybridQuery()` throw a clear error rather than querying a non-existent index.
+- For a **bring-your-own** index (created with `collectionName`), `createIndex()` doesn't auto-create any full-text index. Enabling `textQuery()`/`hybridQuery()` on a caller-owned operational collection is opt-in. Call `createSearchIndex()` explicitly to provision the (billable) text index. Until you do, `textQuery()`/`hybridQuery()` throw a clear error rather than querying a non-existent index.
 
 Naming:
 
-- When `fields` is provided **without** an explicit `searchIndexName`, the field-mapped index is created under a **distinct** default name (`${collectionName}_${indexName}_search_fields_index`, unique per logical index) so it does not collide with — and get silently ignored by — a managed collection's auto-created dynamic index. This distinct index is persisted as the text-search index, so `textQuery()`/`hybridQuery()` use the restricted mapping automatically.
-- When `searchIndexName` is provided, that exact name is used and persisted. `textQuery()`/`hybridQuery()` resolve the persisted name automatically; you can also override the name per call via their `searchIndexName` / `textSearchIndexName` parameters.
+- When `fields` is provided **without** an explicit `searchIndexName`, the field-mapped index is created under a **distinct** default name (`${collectionName}_${indexName}_search_fields_index`, unique per logical index) so it doesn't collide with a managed collection's auto-created dynamic index and get silently ignored. This distinct index is persisted as the text-search index, so `textQuery()`/`hybridQuery()` use the restricted mapping automatically.
+- When `searchIndexName` is provided, that exact name is used and persisted. `textQuery()`/`hybridQuery()` resolve the persisted name automatically. You can also override the name per call via their `searchIndexName` / `textSearchIndexName` parameters.
 
 **indexName** (`string`): Name of the Mastra index whose collection will have the search index
 
@@ -170,7 +170,7 @@ await store.createSearchIndex({
 })
 ```
 
-> **Note:** The field-mapped index name includes the logical `indexName`, so two logical indexes on the same collection get distinct text indexes. Recreating the _same_ logical index with different `fields` still requires dropping the existing index first (`IndexAlreadyExists`).
+The field-mapped index name includes the logical `indexName`, so two logical indexes on the same collection get distinct text indexes. Recreating the _same_ logical index with different `fields` still requires dropping the existing index first (`IndexAlreadyExists`).
 
 ### `waitForSearchIndexReady()`
 
@@ -193,7 +193,7 @@ await store.waitForSearchIndexReady({ indexName: 'precedents' })
 
 Runs a full-text (BM25) search against an Atlas Search index. By default it targets the text-search index recorded for this index (set by `createSearchIndex()`, or the dynamic `${collectionName}_search_index` auto-created by `createIndex()`). Pass `searchIndexName` to target a specific index for this call.
 
-**Note:** metadata filters here (like `hybridQuery()`) are applied via a `$match` stage. For the vector branch of `hybridQuery()`, filters on fields not declared via `filterFields` at index creation are transparently materialised as candidate `_id`s (the same fallback `query()` uses), so undeclared-field filters do not error.
+Metadata filters here (like `hybridQuery()`) are applied via a `$match` stage. For the vector branch of `hybridQuery()`, filters on fields not declared via `filterFields` at index creation are transparently materialised as candidate `_id`s (the same fallback `query()` uses), so undeclared-field filters don't error.
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -220,7 +220,7 @@ const results = await store.textQuery({
 
 ### `hybridQuery()`
 
-Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and on 8.0.x it may need a MongoDB support case to enable — it runs where enabled, e.g. Atlas 8.0.x). A full-text search index must exist: it is auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
+Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable, and it runs where enabled, such as Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -253,7 +253,7 @@ const results = await store.hybridQuery({
 })
 ```
 
-**Note:** `hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage (generally available from 8.1; on 8.0.x it may need a MongoDB support case to enable, and runs where enabled, such as Atlas 8.0.x). If you're running an older version, or `$rankFusion` is not enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
+`hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as Atlas 8.0.x. If you're running an older version, or `$rankFusion` isn't enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
 
 ### `describeIndex()`
 
@@ -276,15 +276,15 @@ interface IndexStats {
 Deletes a vector index. Behavior depends on how the index was created:
 
 - **Managed index** (created without `collectionName`): drops the entire collection and all its data.
-- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index **and**, if one was provisioned via `createSearchIndex()`, the companion full-text search index. The caller's operational collection and its documents are **preserved** — this store never drops a collection it did not create.
+- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index and, if one was provisioned via `createSearchIndex()`, the companion full-text search index. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
 
-The BYO classification is recorded durably when the index is created, so it is applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.
+The BYO classification is recorded durably when the index is created, so it's applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.
 
 **indexName** (`string`): Logical name of the index to delete
 
 ### `listIndexes()`
 
-Lists the **logical** Mastra index names (the `indexName` values passed to `createIndex`), not physical collection names. For a bring-your-own index whose data lives in an operational collection, the logical index name is returned — never the physical collection name — so the value can be passed straight back into `deleteIndex()` / `describeIndex()`. Managed indexes created before durable metadata was introduced are still discovered via their `${name}_vector_index` search index. The internal registry collection is never listed.
+Lists the **logical** Mastra index names (the `indexName` values passed to `createIndex`), not physical collection names. For a bring-your-own index whose data lives in an operational collection, the logical index name is returned instead of the physical collection name. The value can be passed straight back into `deleteIndex()` / `describeIndex()`. Managed indexes created before durable metadata was introduced are still discovered via their `${name}_vector_index` search index. The internal registry collection is never listed.
 
 Returns: `Promise<string[]>`
 
@@ -408,12 +408,12 @@ await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
 
 - The collection must already exist and contain documents with an `embedding` field (or the custom `embeddingFieldPath` you configured)
 - The collection is never created or dropped when using `collectionName`
-- **A BYO index is read-only by default.** `upsert()`, `updateVector()`, `deleteVector()`, and `deleteVectors()` throw a clear error rather than mutating caller-owned operational documents. To let the store write embeddings into (or delete documents from) your collection, opt in explicitly with `createIndex({ ..., allowWrites: true })`. The policy is persisted and survives restarts; entries written by older versions without the flag are treated as read-only (fail closed).
+- **A BYO index is read-only by default.** `upsert()`, `updateVector()`, `deleteVector()`, and `deleteVectors()` throw a clear error rather than mutating caller-owned operational documents. To let the store write embeddings into (or delete documents from) your collection, opt in explicitly with `createIndex({ ..., allowWrites: true })`. The policy is persisted and survives restarts. Entries written by older versions without the flag are treated as read-only (fail closed).
 - Use `metadataMode: 'document'` when querying to retrieve the full source document as `metadata`
 - In `'document'` mode the embedding is omitted from `metadata` by default; pass `includeVector: true` to retain it (and also expose it as a top-level `vector`)
 - **Filtering in `'document'` mode operates on root document fields**, not a nested `metadata.` subdocument. `filter: { lane: 'fraud' }` matches the top-level `lane` field of your operational documents (in the default `'field'` mode, bare fields are rewritten to `metadata.<field>` for managed collections). Both the pushdown and `$match` fallback paths honor this.
 - **Native `ObjectId` `_id`s are supported.** Operational collections commonly key on `ObjectId`; query results coerce `_id` to a string (the `QueryResult.id` contract), and `deleteVector()`/`updateVector()`/`deleteVectors()` accept that string and match the underlying `ObjectId` document. Managed collections (string `_id`s) are unaffected.
-- Full-text and hybrid search on a BYO collection are **opt-in**: no full-text index is auto-created, so call `createSearchIndex()` before `textQuery()`/`hybridQuery()`. The full-text index builds asynchronously — call `waitForSearchIndexReady()` (or pass `waitUntilReady: true`) before an immediate text/hybrid query.
+- Full-text and hybrid search on a BYO collection are **opt-in**: no full-text index is auto-created, so call `createSearchIndex()` before `textQuery()`/`hybridQuery()`. The full-text index builds asynchronously. Call `waitForSearchIndexReady()` (or pass `waitUntilReady: true`) before an immediate text/hybrid query.
 - `deleteIndex()` on a BYO index drops the vector index (and the text index if one was created) but **preserves** the collection and its documents
 
 ## Best practices

package/.docs/reference/voice/livekit.md

@@ -4,7 +4,7 @@
 
 The `@mastra/livekit` package connects Mastra agents to the LiveKit Agents framework. LiveKit runs the audio pipeline (voice activity detection, speech-to-text, turn detection, text-to-speech, barge-in) and the package bridges reply generation to a Mastra agent's `stream()` call.
 
-See [Realtime voice](https://mastra.ai/docs/voice/realtime-voice) for setup and concepts.
+See [Realtime voice](https://mastra.ai/guides/voice/realtime-voice) for setup and concepts.
 
 The package has three entry points:
 
@@ -148,7 +148,7 @@ Returns: `VoiceTurnMessage[]`, where each entry is `{ role: 'system' | 'user' |
 
 ## `MastraLLM`
 
-A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Use it when you build the `voice.AgentSession` yourself and want Mastra in the `llm` slot. [`createLiveKitWorker()`](#createlivekitworker) is the managed alternative. See [Use Mastra as the LLM component](https://mastra.ai/docs/voice/realtime-voice) for how to choose.
+A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Use it when you build the `voice.AgentSession` yourself and want Mastra in the `llm` slot. [`createLiveKitWorker()`](#createlivekitworker) is the managed alternative. See [Use Mastra as the LLM component](https://mastra.ai/guides/voice/realtime-voice) for how to choose.
 
 With `remote`, the plugin streams each turn from your Mastra server over HTTP using Server-Sent Events (SSE). The agent loop, tools, and memory run server-side, and interrupting the agent aborts the server-side generation.
 
@@ -478,5 +478,5 @@ The metadata travels as a JSON string. `liveKitConnectionRoute()` and `dispatchV
 
 ## Related
 
-- [Realtime voice](https://mastra.ai/docs/voice/realtime-voice)
+- [Realtime voice](https://mastra.ai/guides/voice/realtime-voice)
 - [LiveKit Agents docs](https://docs.livekit.io/agents/)

package/.docs/reference/workers/overview.md

@@ -10,14 +10,14 @@ For usage patterns and deployment topologies, see [Workers](https://mastra.ai/do
 
 Controls which workers start in the current process.
 
-| Value                       | Behavior                                                              |
-| --------------------------- | --------------------------------------------------------------------- |
-| _(not set)_                 | Default workers are auto-created based on configuration               |
-| `"false"`                   | Disables all event processing. The process only serves HTTP requests. |
-| `"orchestration"`           | Only the orchestration worker starts                                  |
-| `"scheduler"`               | Only the scheduler worker starts                                      |
-| `"backgroundTasks"`         | Only the background task worker starts                                |
-| `"orchestration,scheduler"` | Multiple workers (comma-separated)                                    |
+| Value                       | Behavior                                                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(not set)_                 | Default workers are auto-created based on configuration                                                                                                   |
+| `"false"`                   | Disables worker event processing. The process serves HTTP requests and can still publish events to PubSub (e.g., workflow starts) without consuming them. |
+| `"orchestration"`           | Only the orchestration worker starts                                                                                                                      |
+| `"scheduler"`               | Only the scheduler worker starts                                                                                                                          |
+| `"backgroundTasks"`         | Only the background task worker starts                                                                                                                    |
+| `"orchestration,scheduler"` | Multiple workers (comma-separated)                                                                                                                        |
 
 Use this to run different worker types in separate containers from the same build artifact.
 
@@ -29,6 +29,8 @@ The base URL of the API server, used by the orchestration worker to execute work
 MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 ```
 
+Use HTTPS URLs in production. See [Security recommendations](https://mastra.ai/docs/server/auth/workers).
+
 The orchestration worker sends step execution requests to:
 
 ```text