@mastra/core 1.18.1-alpha.0 → 1.19.0-alpha.2

package/dist/docs/references/docs-agents-overview.md

@@ -38,7 +38,7 @@ export const mastra = new Mastra({
 
 Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features.
 
-> **Tip:** Use [Studio](https://mastra.ai/docs/getting-started/studio) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
+> **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
 
 > **Note:** Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
 
@@ -48,7 +48,7 @@ After registration, retrieve your agent with [`mastra.getAgentById()`](https://m
 
 When referencing an agent from your Mastra instance, use `mastra.getAgentById()` to ensure it has access to shared services such as instance-level storage, logging, and agent registry. A directly imported agent can still work with its own local configuration, but it won't have access to those shared services.
 
-**Generate**:
+**.generate()**:
 
 Returns the full response after all tool calls and steps complete. The result includes `text`, `toolCalls`, `toolResults`, `steps`, and token `usage` statistics.
 
@@ -58,7 +58,7 @@ const response = await agent.generate('Help me organize my day')
 console.log(response.text)
 ```
 
-**Stream**:
+**.stream()**:
 
 Returns a stream you can consume as tokens arrive. The result exposes `textStream` for incremental output and promises for `toolCalls`, `toolResults`, `steps`, and token `usage` that resolve when the stream finishes.
 
@@ -90,6 +90,6 @@ Once your agent is running, use this table to find the right page for what you w
 
 ## Multi-agent systems
 
-A multi-agent system uses multiple agents to solve a task that is too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
+A multi-agent system uses multiple agents to solve a task that's too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
 
 Read the [conceptual overview of multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems) to learn how you can apply different patterns with Mastra.

package/dist/docs/references/docs-agents-processors.md

@@ -493,7 +493,7 @@ After a `.parallel()` step, each branch result is keyed by its processor ID (e.g
 
 If a branch uses a mutating strategy like `redact`, map to that branch so its transformed messages carry forward. If all branches only `block`, any branch works. Pick any one since none of them modify the messages.
 
-When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the [Studio](https://mastra.ai/docs/getting-started/studio).
+When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the [Studio](https://mastra.ai/docs/studio/overview).
 
 ### Retry mechanism
 

package/dist/docs/references/{docs-observability-datasets-overview.md → docs-evals-datasets-overview.md}

@@ -41,6 +41,16 @@ const { datasets: all } = await datasets.list()
 
 > **Info:** Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/datasets-manager) for the full list of methods.
 
+## Studio
+
+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).
+
+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.
+
+Select **Versions** to see the full history of changes to the dataset. After selecting **Compare Versions**, choose any two versions and select **Compare** to see a side-by-side diff of all items that were added, changed, or removed between those versions.
+
 ## Creating a dataset
 
 Call [`create()`](https://mastra.ai/reference/datasets/create) with a name and optional description:
@@ -176,23 +186,13 @@ 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/observability/datasets/running-experiments).
+You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments).
 
 > **Info:** Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
 
-## Studio
-
-You can also manage datasets in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). 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/observability/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.
-
-Select **Versions** to see the full history of changes to the dataset. After selecting **Compare Versions**, choose any two versions and select **Compare** to see a side-by-side diff of all items that were added, changed, or removed between those versions.
-
 ## Related
 
-- [Running experiments](https://mastra.ai/docs/observability/datasets/running-experiments)
+- [Running experiments](https://mastra.ai/docs/evals/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/dist/docs/references/{docs-observability-datasets-running-experiments.md → docs-evals-datasets-running-experiments.md}

@@ -27,6 +27,14 @@ console.log(summary.failedCount) // number of items that failed
 
 `startExperiment()` blocks until all items finish. For fire-and-forget execution, see [async experiments](#async-experiments).
 
+## Studio
+
+You can also run experiments in [Studio](https://mastra.ai/docs/studio/overview). After you've added a dataset item, open it and select **Run Experiment** and configure the target, scorers, and options.
+
+After running an experiment, the **Experiments** tab shows all runs for that dataset (with status, counts, and timestamps). Select an experiment to see per-item results, scores, and execution traces.
+
+In the **Experiments** tab, select **Compare** and choose two or more experiments to compare their scores and results side by side.
+
 ## Experiment targets
 
 You can point an experiment at a registered agent, workflow, or scorer.
@@ -258,17 +266,9 @@ for (const result of results) {
 
 > **Info:** Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment) for the full parameter and return type documentation.
 
-## Studio
-
-You can also run experiments in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). After you've added a dataset item, open it and select **Run Experiment** and configure the target, scorers, and options.
-
-After running an experiment, the **Experiments** tab shows all runs for that dataset (with status, counts, and timestamps). Select an experiment to see per-item results, scores, and execution traces.
-
-In the **Experiments** tab, select **Compare** and choose two or more experiments to compare their scores and results side by side.
-
 ## Related
 
-- [Datasets overview](https://mastra.ai/docs/observability/datasets/overview)
+- [Datasets overview](https://mastra.ai/docs/evals/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/dist/docs/references/docs-evals-overview.md

@@ -111,9 +111,9 @@ export const contentWorkflow = createWorkflow({ ... })
 
 In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows. This is particularly useful for analyzing past performance, debugging issues, or running batch evaluations.
 
-> **Observability Required:** To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for setup instructions.
+> **Observability required:** To score traces, you must first configure observability in your Mastra instance to collect trace data. See [Tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for setup instructions.
 
-### Scoring traces with Studio
+## Studio
 
 To score traces, you first need to register your scorers with your Mastra instance:
 
@@ -126,16 +126,15 @@ const mastra = new Mastra({
 })
 ```
 
-Once registered, you can score traces interactively within Studio under the Observability section. This provides a user-friendly interface for running scorers against historical traces.
+Once registered, you can score traces interactively within Studio under the **Observability** section. Open Studio to manage scorers, review scores, and run experiments.
 
-## Testing scorers locally
-
-Mastra provides a CLI command `mastra dev` to test your scorers. Studio includes a scorers section where you can run individual scorers against test inputs and view detailed results.
-
-For more details, see [Studio](https://mastra.ai/docs/getting-started/studio) docs.
+- **Scorers list**: Browse all registered scorers with their description, and the number of agents and workflows each scorer is attached to.
+- **Score results**: Select a scorer to see a paginated list of every score it has produced. Click a row to open the detail panel, which shows the score value, reason, input, output, and the prompts used by the judge. From this panel, save any result as a dataset item for future experiments.
+- **Agent Evaluate tab**: Open the Evaluate tab on any agent to attach or detach scorers, create or edit stored scorers inline, manage datasets, and run experiments. Experiment results display per-item scores alongside pass/fail status and version tags.
+- **Trace scoring**: In the Observability section, run a scorer against any historical trace or span to evaluate past interactions. Filter scores by agent or workflow.
 
 ## Next steps
 
 - Learn how to create your own scorers in the [Creating Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide
 - Explore built-in scorers in the [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers) section
-- Test scorers with [Studio](https://mastra.ai/docs/getting-started/studio)
+- Test scorers with [Studio](https://mastra.ai/docs/studio/overview)

package/dist/docs/references/docs-memory-observational-memory.md

@@ -42,7 +42,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 
 ## Benefits
 
-- **Prompt caching**: OM's context is stable — observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
+- **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
 - **Compression**: Raw message history and tool results get compressed into a dense observation log. Smaller context means faster responses and longer coherent conversations.
 - **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, so the agent stays on task over long sessions.
 
@@ -50,7 +50,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 
 You don't remember every word of every conversation you've ever had. You observe what happened subconsciously, then your brain reflects — reorganizing, combining, and condensing into long-term memory. OM works the same way.
 
-Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite — even models with large token limits perform worse when the window is full. This causes two problems:
+Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite; even models with large token limits perform worse when the window is full. This causes two problems:
 
 - **Context rot**: the more raw message history an agent carries, the worse it performs.
 - **Context waste**: most of that history contains tokens no longer needed to keep the agent on task.
@@ -59,14 +59,15 @@ OM solves both problems by compressing old context into dense observations.
 
 ### Observations
 
-When message history tokens exceed a threshold (default: 30,000), the Observer creates observations — concise notes about what happened:
+When message history tokens exceed a threshold (default: 30,000), the Observer creates observations which are concise notes about what happened:
 
 OM uses fast local token estimation for this thresholding work. Text is estimated with `tokenx`, while image parts use provider-aware heuristics so multimodal conversations still trigger observation at the right time. The same applies to image-like `file` parts when a transport normalizes an uploaded image as a file instead of an image part. For example, OpenAI image detail settings can materially change when OM decides to observe.
 
 The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
 
-```text
+```md
 Date: 2026-01-15
+
 - 🔴 12:10 User is building a Next.js app with Supabase auth, due in 1 week (meaning January 22nd 2026)
   - 🔴 12:10 App uses server components with client-side hydration
   - 🟡 12:12 User asked about middleware configuration for protected routes
@@ -77,11 +78,11 @@ The compression is typically 5–40×. The Observer also tracks a **current task
 
 If you enable `observation.threadTitle`, the Observer can also suggest a short thread title when the conversation topic meaningfully changes. Thread title generation is opt-in and updates the thread metadata, so apps like Mastra Code can show the latest title in thread lists and status UI.
 
-Example: an agent using Playwright MCP might see 50,000+ tokens per page snapshot. With OM, the Observer watches the interaction and creates a few hundred tokens of observations about what was on the page and what actions were taken. The agent stays on task without carrying every raw snapshot.
+Example: An agent using Playwright MCP might see 50,000+ tokens per page snapshot. With OM, the Observer watches the interaction and creates a few hundred tokens of observations about what was on the page and what actions were taken. The agent stays on task without carrying every raw snapshot.
 
 ### Reflections
 
-When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them — combining related items and reflecting on patterns.
+When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them, combines related items, and reflects on patterns.
 
 The result is a three-tier system:
 
@@ -93,7 +94,7 @@ The result is a three-tier system:
 
 > **Note:** Retrieval mode is experimental. The API may change in future releases.
 
-Normal OM compresses messages into observations, which is great for staying on task — but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
+Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
 
 #### Browsing only
 
@@ -162,6 +163,16 @@ With retrieval mode enabled, OM:
 
 See the [recall tool reference](https://mastra.ai/reference/memory/observational-memory) for the full API (detail levels, part indexing, pagination, cross-thread browsing, and token limiting).
 
+## Studio
+
+To see how it works in practice, open [Studio](https://mastra.ai/docs/studio/overview) and navigate to an agent with OM enabled. The **Memory** tab displays:
+
+- **Token progress bars**: Current token counts for messages and observations, showing how close each is to its threshold. Hover over the info icon to see the model and threshold for the Observer and Reflector.
+- **Active observations**: The current observation log, rendered inline. When previous observation or reflection records exist, expand "Previous observations" to browse them.
+- **Background processing**: During a conversation, buffered observation chunks and reflection status appear as the agent processes in the background.
+
+The progress bars update live while the agent is observing or reflecting, showing elapsed time and a status badge.
+
 ## Models
 
 The Observer and Reflector run in the background. Any model that works with Mastra's [model routing](https://mastra.ai/models) (`provider/model`) can be used. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
@@ -184,6 +195,8 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 
 ### Token-tiered model selection
 
+**Added in:** `@mastra/memory@1.10.0`
+
 You can use `ModelByInputTokens` to specify different Observer or Reflector models based on input token count. OM selects the matching model tier at runtime from the configured `upTo` thresholds.
 
 ```typescript
@@ -373,10 +386,6 @@ No manual migration needed. OM reads existing messages and observes them lazily
 - **Thread scope**: The first time a thread exceeds `observation.messageTokens`, the Observer processes the backlog.
 - **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take significant time.
 
-## Viewing in Mastra Studio
-
-Mastra Studio shows OM status in real time in the memory tab: token usage, which model is running, current observations, and reflection history.
-
 ## Comparing OM with other memory features
 
 - **[Message history](https://mastra.ai/docs/memory/message-history)**: High-fidelity record of the current conversation

package/dist/docs/references/docs-memory-overview.md

@@ -107,7 +107,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
    > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
 
-5. Call your agent, for example in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
 
 ## Message history
 
@@ -165,7 +165,7 @@ export const memoryAgent = new Agent({
 
 ## Memory in multi-agent systems
 
-When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. There is no flag to enable this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
+When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
 
 ### How delegation scopes memory
 
@@ -175,7 +175,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 - **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
 - **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance. If the subagent defines its own, that takes precedence.
 
-The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation is not stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
 
 > **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Two different subagents under the same supervisor never share a resource ID through delegation.
 
@@ -206,7 +206,7 @@ Because both calls use `resource: 'project-42'`, the writer can access the resea
 
 Enable [Tracing](https://mastra.ai/docs/observability/tracing/overview) to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.
 
-Open [Mastra Studio](https://mastra.ai/docs/getting-started/studio) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
+Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
 
 ## Switch memory per request
 

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -18,18 +18,33 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 ## Quickstart
 
-Semantic recall is enabled by default, so if you give your agent memory it will be included:
+Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
   model: 'openai/gpt-5.4',
-  memory: new Memory(),
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'agent-storage',
+      url: 'file:./local.db',
+    }),
+    vector: new LibSQLVector({
+      id: 'agent-vector',
+      url: 'file:./local.db',
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
+  }),
 })
 ```
 
@@ -77,6 +92,9 @@ const agent = new Agent({
       id: 'agent-vector',
       url: 'file:./local.db',
     }),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -139,6 +157,9 @@ import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 const agent = new Agent({
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
   }),
 })
 ```
@@ -262,26 +283,14 @@ const agent = new Agent({
 
 For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
 
-## Disabling
+## Disable semantic recall
 
-Semantic recall has a performance impact. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
-
-Semantic recall is enabled by default but can be disabled when not needed:
-
-```typescript
-const agent = new Agent({
-  memory: new Memory({
-    options: {
-      semanticRecall: false,
-    },
-  }),
-})
-```
+Semantic recall is disabled by default (`semanticRecall: false`). Each call adds latency because new messages are converted into embeddings and used to query a vector database before the LLM receives them.
 
-You might want to disable semantic recall in scenarios like:
+Keep semantic recall disabled when:
 
-- When message history provides sufficient context for the current conversation.
-- In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
+- Message history provides sufficient context for the current conversation.
+- You're building performance-sensitive applications, like realtime two-way audio, where embedding and vector query latency is noticeable.
 
 ## Viewing recalled messages
 

package/dist/docs/references/docs-memory-storage.md

@@ -14,7 +14,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Sharing the database with Mastra Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
+> **Sharing the database with Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
 >
 > ```typescript
 > url: 'file:/absolute/path/to/your/project/mastra.db'
@@ -129,7 +129,7 @@ Mastra organizes conversations using two identifiers:
 
 Both identifiers are required for agents to store information:
 
-**Generate**:
+**.generate()**:
 
 ```typescript
 const response = await agent.generate('hello', {
@@ -140,7 +140,7 @@ const response = await agent.generate('hello', {
 })
 ```
 
-**Stream**:
+**.stream()**:
 
 ```typescript
 const stream = await agent.stream('hello', {
@@ -151,7 +151,7 @@ const stream = await agent.stream('hello', {
 })
 ```
 
-> **Note:** [Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
+> **Note:** [Studio](https://mastra.ai/docs/studio/overview) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
 
 ### Thread title generation
 

package/dist/docs/references/docs-rag-chunking-and-embedding.md

@@ -9,7 +9,7 @@ const docFromMarkdown = MDocument.fromMarkdown('# Your Markdown content...')
 const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`)
 ```
 
-## Step 1: Document processing
+## Document processing
 
 Use `chunk` to split documents into manageable pieces. Mastra supports multiple chunking strategies optimized for different document types:
 
@@ -65,7 +65,7 @@ const chunks = await doc.chunk({
 
 We go deeper into chunking strategies in our [`chunk()` reference documentation](https://mastra.ai/reference/rag/chunk).
 
-## Step 2: Embedding generation
+## Embedding generation
 
 Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router.
 

package/dist/docs/references/docs-server-auth-composite-auth.md

@@ -225,10 +225,4 @@ function handleUser(user: User) {
     console.log('Clerk user:', user.email)
   }
 }
-```
-
-## Related
-
-- [Auth Overview](https://mastra.ai/docs/server/auth) - Authentication concepts
-- [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth) - Token-to-user mapping
-- [Custom Auth Provider](https://mastra.ai/docs/server/auth/custom-auth-provider) - Build your own provider
+```

package/dist/docs/references/docs-server-auth-custom-auth-provider.md

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

package/dist/docs/references/docs-server-auth-jwt.md

@@ -61,7 +61,7 @@ export const mastra = new Mastra({
 
 > **Info:** Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.
 
-Inside [Studio](https://mastra.ai/docs/getting-started/studio), go to **Settings** and under **Headers** select the **"Add Header"** button. Enter `Authorization` as the header name and `Bearer <your-jwt>` as the value.
+Inside [Studio](https://mastra.ai/docs/studio/overview), go to **Settings** and under **Headers** select the **"Add Header"** button. Enter `Authorization` as the header name and `Bearer <your-jwt>` as the value.
 
 ## Configuring `MastraClient`
 

package/dist/docs/references/docs-server-auth-simple-auth.md

@@ -171,10 +171,4 @@ SimpleAuth is designed for simplicity, not production security:
 - No cryptographic verification
 - All tokens must be known at startup
 
-For production applications, consider using [JWT](https://mastra.ai/docs/server/auth/jwt), [Clerk](https://mastra.ai/docs/server/auth/clerk), [Auth0](https://mastra.ai/docs/server/auth/auth0), or another identity provider.
-
-## Related
-
-- [Auth Overview](https://mastra.ai/docs/server/auth) - Authentication concepts
-- [JWT Auth](https://mastra.ai/docs/server/auth/jwt) - JSON Web Token authentication
-- [Custom Auth Provider](https://mastra.ai/docs/server/auth/custom-auth-provider) - Build your own provider
+For production applications, consider using [JWT](https://mastra.ai/docs/server/auth/jwt), [Clerk](https://mastra.ai/docs/server/auth/clerk), [Auth0](https://mastra.ai/docs/server/auth/auth0), or another identity provider.

package/dist/docs/references/docs-server-custom-adapters.md

@@ -1,6 +1,6 @@
 # Custom adapters
 
-Create a custom adapter when you need to run Mastra with a framework other than Hono or Express. This might be necessary if you have specific request/response handling requirements that `@mastra/hono` and `@mastra/express` don't support.
+Create a custom adapter when the prebuilt server adapters (Hono, Express, Fastify, Koa) don't support your framework or you have specific request/response handling requirements.
 
 A custom adapter translates between Mastra's route definitions and your framework's routing system. You'll implement methods that register middleware, handle requests, and send responses using your framework's APIs.
 
@@ -368,6 +368,8 @@ app.listen(4111)
 ```
 
 > **Tip:** The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server-adapters/hono/src/index.ts) and [@mastra/express](https://github.com/mastra-ai/mastra/blob/main/server-adapters/express/src/index.ts) implementations are good references when building your custom adapter. They show how to handle framework-specific patterns for context storage, middleware registration, and response handling.
+>
+> If you want to use [Studio](https://mastra.ai/docs/studio/overview) with your server adapter, use [`mastra studio`](https://mastra.ai/reference/cli/mastra) to only launch the Studio UI.
 
 ## Related
 

package/dist/docs/references/docs-server-custom-api-routes.md

@@ -262,7 +262,7 @@ For more information about authentication providers, see the [Auth documentation
 
 ## Continue generation after client disconnect
 
-Built-in streaming helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) forward the incoming request's `AbortSignal` to `agent.stream()`. That is the right default when a browser disconnect should cancel the model call.
+Built-in streaming helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) forward the incoming request's `AbortSignal` to `agent.stream()`. That's the right default when a browser disconnect should cancel the model call.
 
 If you want the server to keep generating and persist the final response even after the client disconnects, build a custom route around the underlying `MastraModelOutput`. Start the agent stream without forwarding `c.req.raw.signal`, then call `consumeStream()` in the background so generation continues server-side.
 

package/dist/docs/references/docs-server-mastra-client.md

@@ -10,9 +10,7 @@ To ensure smooth local development, make sure you have:
 - TypeScript `v4.7` or higher (if using TypeScript)
 - Your local Mastra server running (typically on port `4111`)
 
-## Usage
-
-The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.
+> **Note:** The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.
 
 ## Installation
 

package/dist/docs/references/docs-server-mastra-server.md

@@ -43,6 +43,14 @@ export const mastra = new Mastra({
 - **[Mastra Client SDK](https://mastra.ai/docs/server/mastra-client)**: Type-safe client for calling agents, workflows, and tools from browser or server environments.
 - **[Authentication](https://mastra.ai/docs/server/auth)**: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS.
 
+## REST API
+
+You can explore all available endpoints in the OpenAPI specification at <http://localhost:4111/api/openapi.json>, which details every endpoint and its request and response schemas.
+
+To explore the API interactively, visit the Swagger UI at <http://localhost:4111/swagger-ui>. Here, you can discover endpoints and test them directly from your browser.
+
+> **Note:** The OpenAPI and Swagger endpoints are disabled in production by default. To enable them, set [`server.build.openAPIDocs`](https://mastra.ai/reference/configuration) and [`server.build.swaggerUI`](https://mastra.ai/reference/configuration) to `true` respectively.
+
 ## Stream data redaction
 
 When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.

package/dist/docs/references/docs-server-request-context.md

@@ -82,6 +82,23 @@ export const mastra = new Mastra({
 
 > **Info:** Visit [Middleware](https://mastra.ai/docs/server/middleware) for how to use server middleware.
 
+## Studio
+
+When developing locally, you can define named presets in a JSON file and load them into [Studio](https://mastra.ai/docs/studio/overview) with the [`--request-context-presets`](https://mastra.ai/reference/cli/mastra) CLI flag. This adds a dropdown to the request context editor in Studio so you can quickly switch between configurations without manually editing JSON each time.
+
+```bash
+mastra dev --request-context-presets ./presets.json
+```
+
+```json
+{
+  "development": { "userId": "dev-user", "env": "development" },
+  "production": { "userId": "prod-user", "env": "production" }
+}
+```
+
+When you select a preset from the dropdown, the JSON editor populates with that preset's values. Editing the JSON manually switches the dropdown back to **"Custom"**.
+
 ## Accessing values with agents
 
 You can access the `requestContext` argument from any supported configuration options in agents. These functions can be sync or `async`. Use the `.get()` method to read values from `requestContext`.
@@ -446,23 +463,6 @@ requestContextSchema: z.object({
 
 **Handle tool validation errors**: Since tools return error objects instead of throwing, check for errors in your agent or workflow logic when tool execution is critical.
 
-## Testing with Studio presets
-
-When developing locally, you can define named presets in a JSON file and load them into Studio with the [`--request-context-presets`](https://mastra.ai/reference/cli/mastra) CLI flag. This adds a dropdown to the request context editor in Studio so you can quickly switch between configurations without manually editing JSON each time.
-
-```bash
-mastra dev --request-context-presets ./presets.json
-```
-
-```json
-{
-  "development": { "userId": "dev-user", "env": "development" },
-  "production": { "userId": "prod-user", "env": "production" }
-}
-```
-
-When you select a preset from the dropdown, the JSON editor populates with that preset's values. Editing the JSON manually switches the dropdown back to "Custom".
-
 ## Related
 
 - [Agent Request Context](https://mastra.ai/docs/memory/overview)