@mastra/mcp-docs-server 1.2.13-alpha.8 → 1.2.13

package/.docs/docs/getting-started/develop.md

@@ -0,0 +1,196 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Develop
+
+Once you have a Mastra project, you're ready to develop, run, and test your agent.
+
+## Run Mastra locally
+
+The fastest way to see your agent working is in [Mastra Studio](https://mastra.ai/docs/studio/overview). From your project root, start Studio and the local development server with [`mastra dev`](https://mastra.ai/reference/cli/mastra):
+
+**npm**:
+
+```bash
+npx mastra dev
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra dev
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra dev
+```
+
+**Bun**:
+
+```bash
+bun x mastra dev
+```
+
+Open Studio at [`http://localhost:4111`](http://localhost:4111) to test your agent and inspect its runs.
+
+The development server also exposes APIs for your agents, tools, and workflows. Open [`http://localhost:4111/api`](http://localhost:4111/api) to browse what's available, then connect your frontend using the [Mastra Client](https://mastra.ai/docs/server/mastra-client).
+
+Changes in your `src/mastra/` directory automatically restart the development server, so you don't need to restart it manually as you build.
+
+## Build with AI
+
+Mastra provides a skill and a CLI to help your coding agent write high-quality Mastra code.
+
+### Mastra skill
+
+AI models may not have up-to-date knowledge of Mastra's APIs. Use the [Mastra skill](https://github.com/mastra-ai/skills) to give your coding agent implementation guidance, best practices, and instructions for fetching the latest Mastra documentation.
+
+Install the skill manually with:
+
+**npm**:
+
+```bash
+npx skills add mastra-ai/skills
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills add mastra-ai/skills
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills add mastra-ai/skills
+```
+
+**Bun**:
+
+```bash
+bun x skills add mastra-ai/skills
+```
+
+Periodically update the skill to get the latest guidance:
+
+**npm**:
+
+```bash
+npx skills update mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills update mastra
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills update mastra
+```
+
+**Bun**:
+
+```bash
+bun x skills update mastra
+```
+
+> **Note:** When you create a project with [create mastra](https://mastra.ai/docs), the command automatically installs the Mastra skill so your coding agent can discover and use it.
+
+### Mastra CLI
+
+Use the [`mastra` CLI](https://mastra.ai/reference/cli/mastra) to give your coding agent a feedback loop for testing updates and inspecting results. The CLI gives it access to agents, workflows, tools, memory, evals, traces, and logs.
+
+For example, your coding agent can run an agent, then pull traces to inspect the results:
+
+```bash
+npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
+npx mastra api --url http://localhost:4111 trace list
+```
+
+Remember to install the [Mastra skill](#mastra-skill) to teach your coding agent how to use the CLI.
+
+## Project structure
+
+One of the first decisions when adopting a framework is how to structure the project. We recommend keeping framework code under `src/mastra/`, with related primitives grouped into their own files or folders. Use `src/mastra/index.ts` as the central place to configure and register them.
+
+A minimal project can look like this:
+
+```text
+src/
+  mastra/
+    agents/
+      agent.ts
+    tools/
+      tool.ts
+    workflows/
+      workflow.ts
+    scorers/
+      scorer.ts
+    skills.ts
+    index.ts
+```
+
+See the [project structure reference](https://mastra.ai/reference/project-structure) for the default layout and recommended conventions.
+
+## File-based agents
+
+> **Beta:** File-based agents are in beta and may change before they're stable.
+
+> **📹 Watch:** [How to create your first file-based agent](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)
+
+With file-based agents, Mastra automatically [discovers](https://mastra.ai/reference/file-based-agents/config) agents and related primitives from supported files under `src/mastra/`. You organize those files by convention instead of importing and registering each primitive on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
+
+The file system becomes a direct representation of your project structure, so you and your coding agent can understand how the project fits together without tracing how everything is wired together in code.
+
+You can use file-based agents throughout your project or adopt them incrementally alongside primitives defined in code. Not every Mastra feature or use case is supported yet.
+
+### Create your first agent
+
+A file-based agent lives in its own directory under `src/mastra/agents/`. To create a working agent, add a `config.ts` file for its model and runtime options and an `instructions.md` file for its always-on prompt:
+
+```text
+src/mastra/agents/
+  writing-assistant/
+    config.ts
+    instructions.md
+```
+
+The directory name becomes the agent's default `id` and `name`. In this example, Mastra registers the agent as `writing-assistant`.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.6-sol',
+})
+```
+
+```markdown
+Rewrite text clearly and concisely.
+```
+
+Run `npx mastra dev`, open Studio, and select `writing-assistant` to test it.
+
+### How discovery works
+
+Mastra uses paths to discover and name file-based capabilities. An agent directory supplies the default agent `id` and `name`. For example, `tools/search_docs.ts` registers a tool as `search_docs`, while `skills/style-guide.md` registers a skill as `style-guide`. See the extension paths below.
+
+### Extend your agent
+
+Add files or directories when your agent needs more functionality:
+
+| Path                                                                                       | What it adds                                      |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| [`tools/<tool-name>.ts`](https://mastra.ai/reference/file-based-agents/tools)              | Functions the model can call                      |
+| [`skills/<skill-name>.md`](https://mastra.ai/reference/file-based-agents/skills)           | Detailed guidance the agent loads when relevant   |
+| [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)                        | Conversation history and working context          |
+| [`workspace.ts` and `workspace/`](https://mastra.ai/reference/file-based-agents/workspace) | Filesystem and shell access                       |
+| [`subagents/<agent-id>/`](https://mastra.ai/reference/file-based-agents/subagents)         | Specialist agents that the parent can delegate to |
+
+Keep each capability next to the agent that uses it. Mastra discovers and registers these files when the development server starts or restarts.
+
+Browse the [file-based agents reference](https://mastra.ai/reference/file-based-agents/config) for all supported file conventions and configuration options.

package/.docs/docs/index.md

@@ -166,4 +166,81 @@ For other frameworks, see the [framework integration guides](https://mastra.ai/g
 
 Browse [templates](https://mastra.ai/templates) for complete Mastra projects you can clone and adapt.
 
-> **Note:** New to Mastra? Read [What's Mastra?](https://mastra.ai/docs/what-is-mastra) for an overview of the framework, its capabilities, and what you can build with it.
+## Use cases
+
+<details>
+**Embed agents in your product**
+
+Add AI capabilities to your platform so your users can build or interact with agents.
+
+Used by [Replit](https://mastra.ai/blog/replitagent3), [Fireworks](https://mastra.ai/blog/fireworks-xml-prompting), [Medusa](https://mastra.ai/blog/medusa-ecommerce)
+
+</details>
+
+<details>
+**Customer-facing assistants**
+
+Build agents that handle inquiries, schedule appointments, send reminders, and answer questions via chat, WhatsApp, or voice.
+
+Used by [Vetnio](https://mastra.ai/blog/vetnio), [Lua](https://mastra.ai/blog/lua-scaling)
+
+Templates: [Docs Chatbot](https://mastra.ai/templates/docs-chatbot), [Slack Agent](https://mastra.ai/templates/slack-agent)
+
+</details>
+
+<details>
+**Internal copilots**
+
+Help employees work faster with AI that understands your domain, such as HR queries, clinical documentation, sales prep, or document generation.
+
+Used by [Factorial](https://mastra.ai/blog/factorial-case-study), [Counsel Health](https://mastra.ai/blog/counsel-health), [Cedar](https://mastra.ai/blog/cedar-case-study), [SoftBank](https://mastra.ai/blog/softbank-productivity-mastra-2025-08-20)
+
+Templates: [Chat with PDF](https://mastra.ai/templates/chat-with-pdf), [Google Sheet Analysis](https://mastra.ai/templates/google-sheets-analysis)
+
+</details>
+
+<details>
+**Data analysis agents**
+
+Let users query databases and dashboards in natural language. Connect to your data sources and return answers, charts, or reports.
+
+Used by [Index](https://mastra.ai/blog/index-case-study), [PLAID Japan](https://mastra.ai/blog/plaid-jpn-gcp-agents)
+
+Templates: [Chat with Database](https://mastra.ai/templates/text-to-sql), [CSV to Questions](https://mastra.ai/templates/csv-to-questions)
+
+</details>
+
+<details>
+**Content automation**
+
+Generate, transform, and manage structured content at scale for a content management system, knowledge base, or documentation system.
+
+Used by [Sanity](https://mastra.ai/blog/sanity)
+
+Templates: [Chat with YouTube](https://mastra.ai/templates/chat-with-youtube), [Flash Cards from PDF](https://mastra.ai/templates/flash-cards-from-pdf)
+
+</details>
+
+<details>
+**DevOps and engineering automation**
+
+Automate deployments, debug production issues, manage infrastructure, and handle on-call workflows.
+
+Used by [StarSling](https://mastra.ai/blog/starsling)
+
+Templates: [GitHub PR Code Review](https://mastra.ai/templates/github-pr-code-review-agent), [Browser Agent](https://mastra.ai/templates/browsing-agent)
+
+</details>
+
+<details>
+**Sales and go-to-market workflows**
+
+Turn customer conversations into structured tasks, generate investment memos, or automate outreach sequences.
+
+Used by [Kestral](https://mastra.ai/blog/kestral), [Orange Collective](https://mastra.ai/blog/orange-collective-vc-operating-system), [WorkOS](https://mastra.ai/blog/workos-teaching-mastra)
+
+Templates: [Customer Feedback Summarization](https://mastra.ai/templates/customer-feedback-summarization)
+
+</details>
+
+> **Video:** [A quick tour of the Mastra platform](https://www.youtube.com/watch?v=NosES9aJxCc) shows how the pieces fit together.

package/.docs/docs/mastra-platform/workspaces.md

@@ -9,7 +9,7 @@ Every workspace exposes two capabilities:
 - One **bucket** for filesystem storage, wrapped by [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem). The bucket is a durable, environment-scoped store agents read from and write to across runs.
 - A pool of **on-demand sandboxes** for command execution, wrapped by [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox). Each `PlatformSandbox` instance provisions its own remote sandbox on `start()` and destroys it on `destroy()`. Agents typically spin up many sandboxes per session, use them for a task, and let them go.
 
-Workspaces are scoped to a single [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` don't share buckets or sandbox pools. The platform manages provisioning, credentials, and idle cleanup. Your deploy only constructs the providers.
+Workspaces are scoped to a single [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` don't share buckets or sandbox pools. The platform manages provisioning, authentication, and idle cleanup.
 
 ## When workspaces are provisioned
 
@@ -68,11 +68,11 @@ export const mastra = new Mastra({
 })
 ```
 
-`PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
+`PlatformFilesystem` and `PlatformSandbox` read their configuration from environment variables, so you don't pass any options on the platform. The platform injects them at deploy time. See [Environment variables](#environment-variables).
 
 ## One bucket, many sandboxes
 
-The two providers have different lifecycles, and the difference matters when you design agents.
+`PlatformFilesystem` and `PlatformSandbox` have different lifecycles, which matters when you design agents.
 
 **`PlatformFilesystem` is a long-lived handle to the environment's bucket.** All requests, all agents, and all sandboxes in the environment read and write the same object storage. Anything an agent writes is visible on the next request unless you explicitly delete it.
 
@@ -109,25 +109,25 @@ await perProjectSandbox.start()
 
 See [`PlatformSandbox` reference](https://mastra.ai/reference/workspace/platform-sandbox) for the full lifecycle, checkpoint recovery, reattachment, and clone options.
 
-## Injected environment variables
+## Environment variables
 
-Every deploy that runs on a platform environment with a workspace receives these variables:
+Every deploy that runs on a platform environment with a workspace receives these variables automatically:
 
-| Variable                      | Contents                                                                                                                                                 |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MASTRA_PLATFORM_SECRET_KEY`  | Secret key scoped to the deploy. Used by the workspace providers to authenticate. `MASTRA_PLATFORM_ACCESS_TOKEN` is also injected as a deprecated alias. |
-| `MASTRA_PROJECT_ID`           | Project the deploy belongs to.                                                                                                                           |
-| `MASTRA_ENVIRONMENT_ID`       | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                         |
-| `MASTRA_PLATFORM_BUCKET_NAME` | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                                     |
+| Variable                       | Contents                                                                                                                                        |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_ACCESS_TOKEN` | Platform-issued JSON Web Token (JWT) the workspace providers use to authenticate. The token is scoped to the deploy's organization and project. |
+| `MASTRA_PROJECT_ID`            | Project the deploy belongs to.                                                                                                                  |
+| `MASTRA_ENVIRONMENT_ID`        | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                |
+| `MASTRA_PLATFORM_BUCKET_NAME`  | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                            |
 
 These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
 
 ## Local development
 
-Reuse the same providers locally by putting the four variables in your `.env` file. Get the values from your project's Workspaces tab:
+Reuse the same providers locally by putting the four variables in your `.env` file. Get the project, environment, and bucket values from your project's **Workspaces** tab. For `MASTRA_PLATFORM_ACCESS_TOKEN`, create an `sk_` API token on your organization's settings page under **API Tokens**. Platform deploys use an injected JWT instead.
 
 ```bash
-MASTRA_PLATFORM_SECRET_KEY=your-secret-key
+MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
 MASTRA_PROJECT_ID=your-project-id
 MASTRA_ENVIRONMENT_ID=your-environment-id
 MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

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

@@ -476,6 +476,29 @@ const memory = new Memory({
 })
 ```
 
+#### Custom recall guidance
+
+Mastra injects scope-aware instructions that teach the agent when to search, list threads, or read a specific thread. Use `instructions` to append application-specific guidance after those built-in instructions. The built-in instructions are never replaced:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      retrieval: {
+        vector: true,
+        instructions: `
+          Prefer the current conversation when it already contains the answer.
+          For an initial scan, use a small limit with detail="low".
+        `,
+      },
+    },
+  },
+})
+```
+
+This keeps recall-specific guidance attached to the recall tool instead of the agent's global instructions, so it doesn't affect unrelated tasks.
+
 #### What retrieval enables
 
 With retrieval mode enabled, OM:

package/.docs/docs/studio/observability.md

@@ -96,6 +96,10 @@ Visit the [metrics overview](https://mastra.ai/docs/observability/metrics/overvi
 
 When you run an agent or workflow, the Observability tab displays traces that highlight the key AI operations such as model calls, tool executions, and workflow steps. Follow these traces to see how data moves, where time is spent, and what's happening under the hood.
 
+Above the trace list, open **Columns** to show or hide input, entity, duration, input token, output token, estimated cost, and custom metadata columns. To display custom metadata, add the top-level key used in `tracingOptions.metadata`. Studio saves the selection in browser storage for the current Mastra server and API prefix.
+
+Token and estimated cost columns require an observability store that supports metrics. These columns stay hidden in the **Branches** view because several branch rows can belong to the same trace.
+
 Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
 
 To export a trace, select **Download trace JSON** in the trace panel header. This saves the entire trace as a `trace-<id>.json` file, with every span and its full input, output, metadata, and attributes. Use it to share a trace or attach it to a bug report, or alternatively build an evaluation dataset offline.

package/.docs/docs/studio/overview.md

@@ -103,13 +103,13 @@ The Scorers tab displays the results of your agent's scorers as they run. When m
 
 Create and manage collections of test cases to evaluate your agents and workflows. Import items from CSV or JSON and define input and ground-truth schemas, plus pin to specific versions so you can reproduce experiments exactly. Run experiments with [scorers](https://mastra.ai/docs/evals/overview) to compare quality across prompts, models, or code changes.
 
-See [datasets overview](https://mastra.ai/docs/evals/datasets/overview) for the full API and versioning details.
+See [datasets overview](https://mastra.ai/docs/datasets/overview) for the full API and versioning details.
 
 ### Experiments
 
 Run all items in a dataset against an agent, workflow, or scorer and collect the results in one place. Select a target, optionally attach scorers, and trigger the experiment. The results view shows each item's input, output, status, and individual score breakdowns. Compare two experiments side by side to measure the impact of prompt, model, or code changes.
 
-See [datasets overview](https://mastra.ai/docs/evals/datasets/overview) for setup details.
+See [datasets overview](https://mastra.ai/docs/datasets/overview) for setup details.
 
 ## Observability
 

package/.docs/docs/workspace/search.md

@@ -280,5 +280,5 @@ When you configure search on a workspace, agents receive tools for searching and
 ## Related
 
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
-- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [RAG overview](https://mastra.ai/guides/rag/overview)
 - [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/guides/getting-started/quickstart.md

@@ -2,11 +2,11 @@
 
 # Mastra Quickstart
 
-**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install).
+**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/guides/getting-started/manual-install).
 
 The `create-mastra` CLI is the quickest way to start a Mastra project. It creates an agent harness with workspace tools, memory, task tracking, web access, schedules, storage, and observability.
 
-For more control, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
+For more control, see the [manual installation guide](https://mastra.ai/guides/getting-started/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
 > **📹 Watch:** Watch the [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
 
@@ -83,6 +83,6 @@ Open [Studio at localhost:4111](http://localhost:4111), select the agent, and se
 ## Next steps
 
 - Integrate Mastra with [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
-- Learn how to [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
+- Learn how to [build Mastra with AI](https://mastra.ai/reference/build-with-ai)
 - Build an agent from scratch with a [guide](https://mastra.ai/guides)
 - Watch the [Mastra YouTube channel](https://www.youtube.com/@mastra-ai)

package/.docs/{docs → guides}/rag/chunking-and-embedding.md

@@ -181,5 +181,5 @@ For more examples of different chunking strategies and embedding configurations,
 
 For more details on vector databases and embeddings, see:
 
-- [Vector Databases](https://mastra.ai/docs/rag/vector-databases)
+- [Vector Databases](https://mastra.ai/guides/rag/vector-databases)
 - [Embedding API Reference](https://mastra.ai/reference/rag/embeddings)

package/.docs/{docs → guides}/rag/graph-rag.md

@@ -14,7 +14,7 @@ GraphRAG is particularly effective when:
 - Understanding connections between concepts is important
 - Simple vector similarity misses important contextual relationships
 
-For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/docs/rag/retrieval).
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/guides/rag/retrieval).
 
 ## How GraphRAG works
 

package/.docs/{docs → guides}/rag/overview.md

@@ -63,11 +63,11 @@ This example shows the essentials. Initialize a document and create chunks, then
 
 ## Document processing
 
-The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/docs/rag/chunking-and-embedding).
+The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/guides/rag/chunking-and-embedding).
 
 ## Vector storage
 
-Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/docs/rag/vector-databases).
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
 
 ## More resources
 

package/.docs/{docs → guides}/rag/retrieval.md

@@ -517,4 +517,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.

package/.docs/{docs → guides}/voice/overview.md

@@ -29,7 +29,7 @@ You can then use the following voice capabilities:
 
 Turn your agent's responses into natural-sounding speech using Mastra's TTS capabilities. Choose from multiple providers like OpenAI, ElevenLabs, and more.
 
-For detailed configuration options and advanced features, check out our [Text-to-Speech guide](https://mastra.ai/docs/voice/text-to-speech).
+For detailed configuration options and advanced features, check out our [Text-to-Speech guide](https://mastra.ai/guides/voice/text-to-speech).
 
 **OpenAI**:
 
@@ -331,7 +331,7 @@ Visit the [Murf Voice Reference](https://mastra.ai/reference/voice/murf) for mor
 
 ### Speech to Text (STT)
 
-Transcribe spoken content using providers like OpenAI, ElevenLabs, and more. For detailed configuration options and more, check out [Speech to Text](https://mastra.ai/docs/voice/speech-to-text).
+Transcribe spoken content using providers like OpenAI, ElevenLabs, and more. For detailed configuration options and more, check out [Speech to Text](https://mastra.ai/guides/voice/speech-to-text).
 
 You can download a sample audio file from [here](https://github.com/mastra-ai/realtime-voice-demo/raw/refs/heads/main/how_can_i_help_you.mp3).
 
@@ -564,7 +564,7 @@ Visit the [Sarvam Voice Reference](https://mastra.ai/reference/voice/sarvam) for
 
 ### Speech to Speech (STS)
 
-Create conversational experiences with speech-to-speech capabilities. The unified API enables real-time voice interactions between users and AI agents. For detailed configuration options and advanced features, check out [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech).
+Create conversational experiences with speech-to-speech capabilities. The unified API enables real-time voice interactions between users and AI agents. For detailed configuration options and advanced features, check out [Speech to Speech](https://mastra.ai/guides/voice/speech-to-speech).
 
 **OpenAI**:
 
@@ -775,7 +775,7 @@ Visit the [xAI Realtime Voice Reference](https://mastra.ai/reference/voice/xai-r
 
 ### Realtime voice
 
-Run live calls a user can talk over, in the browser or over the phone. Mastra hands the audio loop to LiveKit, which covers voice activity detection, semantic turn detection, and barge-in, while your agent generates each reply with its own model, tools, and memory. For setup and configuration options, check out [Realtime voice](https://mastra.ai/docs/voice/realtime-voice).
+Run live calls a user can talk over, in the browser or over the phone. Mastra hands the audio loop to LiveKit, which covers voice activity detection, semantic turn detection, and barge-in, while your agent generates each reply with its own model, tools, and memory. For setup and configuration options, check out [Realtime voice](https://mastra.ai/guides/voice/realtime-voice).
 
 ## Voice configuration
 

package/.docs/{docs → guides}/voice/realtime-voice.md

@@ -6,7 +6,7 @@ Realtime voice turns a Mastra agent into a live call a user can talk over, in th
 
 The [`@mastra/livekit`](https://mastra.ai/reference/voice/livekit) package connects Mastra agents to the [LiveKit Agents framework](https://docs.livekit.io/agents/): LiveKit owns the audio loop like voice activity detection, streaming speech-to-text, semantic turn detection, barge-in, and text-to-speech. Your Mastra agent generates every reply with its own model, tools, and memory.
 
-Use realtime voice when you need low-latency, interruptible voice conversations. For provider-based speech-to-speech without LiveKit, see [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech).
+Use realtime voice when you need low-latency, interruptible voice conversations. For provider-based speech-to-speech without LiveKit, see [Speech to Speech](https://mastra.ai/guides/voice/speech-to-speech).
 
 ## Quickstart
 
@@ -399,6 +399,6 @@ Conversation history lives in Mastra Memory, so voice sessions and text chat can
 ## Related
 
 - [`@mastra/livekit` reference](https://mastra.ai/reference/voice/livekit)
-- [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech)
+- [Speech to Speech](https://mastra.ai/guides/voice/speech-to-speech)
 - [Agent Memory](https://mastra.ai/docs/memory/overview)
 - [LiveKit Agents docs](https://docs.livekit.io/agents/)

package/.docs/{docs → guides}/voice/speech-to-speech.md

@@ -54,7 +54,7 @@ const micStream = getMicrophoneStream()
 await agent.voice.send(micStream)
 ```
 
-For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/guides/voice/overview).
 
 ## Use tools in realtime sessions
 

package/.docs/{docs → guides}/voice/speech-to-text.md

@@ -96,4 +96,4 @@ const transcription = await agent.voice.listen(audioStream, {
 console.log(`Transcription: ${transcription}`)
 ```
 
-For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/guides/voice/overview).

package/.docs/{docs → guides}/voice/text-to-speech.md

@@ -4,7 +4,7 @@
 
 Text-to-Speech (TTS) in Mastra offers a unified API for synthesizing spoken audio from text using providers. By incorporating TTS into your applications, you can enhance user experience with natural voice interactions and improve accessibility for users with visual impairments, plus create more engaging multimodal interfaces.
 
-TTS is a core component of any voice application. Combined with STT (Speech-to-Text), it forms the foundation of voice interaction systems. Newer models support STS ([Speech-to-Speech](https://mastra.ai/docs/voice/speech-to-speech)) which can be used for real-time interactions but come at high cost ($).
+TTS is a core component of any voice application. Combined with STT (Speech-to-Text), it forms the foundation of voice interaction systems. Newer models support STS ([Speech-to-Speech](https://mastra.ai/guides/voice/speech-to-speech)) which can be used for real-time interactions but come at high cost ($).
 
 ## Configuration
 
@@ -102,4 +102,4 @@ await new Promise<void>((resolve, reject) => {
 })
 ```
 
-For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/docs/voice/overview).
+For a broader overview of voice providers on agents, see [Voice in Mastra](https://mastra.ai/guides/voice/overview).