@mastra/mcp-docs-server 1.2.7-alpha.18 → 1.2.7-alpha.20

package/.docs/docs/agents/code-mode.md

@@ -126,6 +126,22 @@ const agent = new Agent({
 
 The generated code for `sales_code` can't call an inventory tool, and the reverse holds too. Use this for least-privilege scoping and to keep each tool's prompt surface small.
 
+## Remote sandboxes
+
+By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/reference/workspace/e2b-sandbox)), where the host paths don't exist.
+
+Remote sandboxes need a transport that writes the program into the sandbox filesystem. For E2B, pass the shipped `E2BCodeModeTransport` as the second argument to `createCodeMode`:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'
+
+const { tool, instructions } = createCodeMode(
+  { tools, sandbox: new E2BSandbox() },
+  new E2BCodeModeTransport(),
+)
+```
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)

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

@@ -2,13 +2,13 @@
 
 # Configuration
 
-When you deploy to the Mastra platform, the CLI generates a `.mastra-project.json` config file and reads environment variables from your local `.env` files.
+When you deploy to the Mastra platform, the CLI generates a `.mastra-project.json` config file and resolves environment variables from the platform and, optionally, your local `.env` files.
 
-This page explains both mechanisms and how they differ between Studio and Server deployments.
+This page explains both mechanisms.
 
 ## Project config
 
-The `.mastra-project.json` file is auto-generated on your first Studio or Server deploy. It links your local project to a platform project. The [GitHub integration](https://mastra.ai/docs/mastra-platform/github) writes the same file into linked repositories.
+The `.mastra-project.json` file is auto-generated on your first [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy). It links your local project to a platform project. The [GitHub integration](https://mastra.ai/docs/mastra-platform/github) writes the same file into linked repositories.
 
 Commit it to your version control so that subsequent deploys (including from CI) target the correct project.
 
@@ -30,19 +30,20 @@ Your file will look something like this:
 
 ## Environment variables
 
-The CLI reads from `.env` and `.env.local` files in your project directory during deploy. Variables from `.env.local` override those in `.env`.
+A local env file is optional. [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) resolves variables from three sources:
 
-You can set environment variables like so:
+- **Managed variables**: Injected by platform resources like [hosted databases](https://mastra.ai/docs/mastra-platform/database). The platform defines these, and you can't edit them.
+- **Stored variables**: Saved on the project or environment through the dashboard. Used as-is on every deploy with no local file needed.
+- **Local env files**: An explicit `--env-file`, or ambient `.env` and `.env.local` files, layered on top at deploy time. Variables from `.env.local` override those in `.env`.
 
-- **Studio**: Environment variables are read from your local `.env` files and bundled into the deploy artifact. To update them, redeploy.
-- **Server**: On the first deploy, the CLI automatically seeds environment variables from your local `.env` files. After that, manage them per-project through the dashboard or API.
-
-To pin the deploy to a specific env file (instead of relying on the default selection), pass `--env-file`:
+To pin the deploy to a specific env file instead of relying on the default selection, pass `--env-file`:
 
 ```bash
-mastra studio deploy --env-file .env.production --yes
+mastra deploy --env-file .env.production --yes
 ```
 
+Review and sanitize local env files before deploying to avoid uploading development-only or personal secrets.
+
 ### Observability
 
 The following environment variables configure the Observability product on the Mastra platform.
@@ -58,19 +59,11 @@ The following environment variables configure the Observability product on the M
 
 ## Multiple environments
 
-A platform project maps to a single deployed instance with one set of env vars. Platform projects don't have built-in `staging` vs `production` slots. To run the same codebase across multiple environments, create one project per environment and use the matching `.mastra-project.json` file for each deploy.
+A single project runs the same codebase across multiple [environments](https://mastra.ai/docs/mastra-platform/environments), such as `production` and `staging`. Each environment has its own URL, its own stored variables, and its own deploy history. One `.mastra-project.json` file covers all of them:
 
 ```bash
-# Create and deploy each environment for the first time.
-mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
-mastra studio deploy --project "my-app-production" --env-file .env.production --yes
-
-# For subsequent deploys, restore the matching .mastra-project.json file before deploying.
-cp .mastra-project.staging.json .mastra-project.json
-mastra studio deploy --env-file .env.staging --yes
-
-cp .mastra-project.production.json .mastra-project.json
-mastra studio deploy --env-file .env.production --yes
+mastra deploy --env production --yes
+mastra deploy --env staging --env-file .env.staging --yes
 ```
 
-Each project has its own Studio URL and can send observability data to the Mastra platform. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_ACCESS_TOKEN` per environment so traces route to the matching platform project.
+> **Note:** Earlier platform versions required one project per environment. Environments replace that pattern, so keep one project and deploy to named environments instead.

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

@@ -2,7 +2,11 @@
 
 # Hosted databases
 
-From your [platform](https://mastra.ai/docs/mastra-platform/overview) project settings, provision a fully managed database and attach it to your project. Mastra creates it with your provider, stores credentials securely, and injects connection details as runtime environment variables when the database is ready, so there are no connection strings to copy or configure.
+Provision a fully managed database from the CLI or your [platform](https://mastra.ai/docs/mastra-platform/overview) project settings and attach it to your project. Mastra creates it with your provider, stores credentials securely, and injects connection details as runtime environment variables when the database is ready, so there are no connection strings to copy or configure.
+
+```bash
+mastra env db create --kind turso
+```
 
 ## When to use hosted databases
 
@@ -14,9 +18,9 @@ Use a hosted database when your project needs durable storage that's managed by
 
 ## Providers
 
-Hosted databases are available through three providers. Pick one when you attach a database from project settings. Mastra provisions it with the provider, stores credentials securely, and injects connection details as runtime environment variables when the database is ready. Wire those variables into the matching Mastra storage adapter in your code.
+Hosted databases are available through two providers today — Turso and Postgres — with MongoDB coming soon. Pick one when you attach a database, then wire its injected variables into the matching Mastra storage adapter in your code.
 
-You can attach one database per provider to a project. This keeps environment variable names unambiguous — for example, a project has a single `DATABASE_URL` for Postgres and separate `TURSO_*` variables for Turso. Attach Turso and Postgres to the same project when you need separate stores for different workloads.
+Each provider injects a fixed set of variable names — for example, a single `DATABASE_URL` for Postgres and separate `TURSO_*` variables for Turso. Those names must be unique within each environment, which means an environment can use at most one database per provider. Attach Turso and Postgres to the same project when you need separate stores for different workloads.
 
 For most agent-focused projects, **Turso** is the simplest starting point. It provides a lightweight, SQLite-compatible engine well suited to agent memory, conversation history, and per-tenant isolation. Choose **Postgres** when your workload needs full SQL, relational schemas, or structured application data beyond Mastra runtime state. **MongoDB** (_coming soon_) will add document storage and built-in vector search for workloads that don't map cleanly to SQL.
 
@@ -26,7 +30,47 @@ For most agent-focused projects, **Turso** is the simplest starting point. It pr
 | **PostgreSQL** | Serverless Postgres        | Relational workloads, structured data           |
 | **MongoDB**    | Document and vector search | Document storage, vector search (_coming soon_) |
 
-## Attach a database
+## Database scope
+
+A database is attached at one of two scopes:
+
+- **Project scope**: The default. One database shared by all of the project's [environments](https://mastra.ai/docs/mastra-platform/environments). Its variables are injected into every deploy.
+- **Environment scope**: Attached to a single environment. Use this to isolate data between environments, for example separate production and staging databases.
+
+The scope is set when you attach the database and shown in `mastra env db list`.
+
+The two scopes can't overlap for the same provider. Because a project-scoped database already injects its variables into every environment, attaching an environment-scoped database of the same provider is rejected with a variable name conflict. To move from a shared database to per-environment databases, delete the project-scoped database first, then attach one database per environment. Deleting a database destroys it with the provider along with all of its data — export anything you need to keep before switching scopes. Environment-scoped databases on different environments never conflict — each deploy only receives the variables for its own environment.
+
+## Attach with the CLI
+
+Create and attach a database in one command. The CLI polls until it's ready, which takes a few seconds:
+
+```bash
+# Shared by all environments
+mastra env db create --kind turso
+
+# Scoped to the staging environment
+mastra env db create staging --kind turso
+```
+
+Supported kinds are `turso` and `neon` (Postgres). Useful flags:
+
+- `--name <name>`: Database name. Defaults to a name derived from the project slug.
+- `--region <region>`: Provider region ID for project-scoped databases (for example `fra`). Environment-scoped databases are placed near the environment's region automatically, and an explicit `--region` is ignored.
+- `--no-wait`: Return immediately instead of polling. Check progress later with `mastra env db show`.
+- `--json`: Machine-readable output.
+
+Inspect and manage attached databases:
+
+```bash
+mastra env db list
+mastra env db show <database>
+mastra env db delete <database>
+```
+
+`mastra env db list` shows each database's kind, status, scope, and injected variable names. `mastra env db show` prints connection instructions with secret values masked; pass `--show-secrets` to reveal them. `mastra env db delete` permanently deletes the database and all of its data with the provider. Creating and deleting databases requires the admin role in your organization.
+
+## Attach from project settings
 
 1. Open your project in the [platform](https://mastra.ai/docs/mastra-platform/overview) and go to **Project Settings**.
 
@@ -41,7 +85,7 @@ For most agent-focused projects, **Turso** is the simplest starting point. It pr
 
 5. Select **Attach database**. Provisioning runs in the background. The database starts in a `provisioning` state and moves to `ready` once the provider finishes setup. Connection details are injected into your project as server runtime environment variables automatically.
 
-> **Note:** Hosted databases are created from your platform project settings. No CLI or public API currently provisions them.
+Databases attached from project settings are project-scoped. Use the [CLI](#attach-with-the-cli) to attach an environment-scoped database.
 
 ## Connect from your code
 
@@ -149,4 +193,4 @@ Each provider injects a fixed set of managed environment variables. These are av
 ## Manage a database
 
 - **View connection details**: Open a `ready` database in your project settings to see its environment variables and a copy-pasteable code snippet.
-- **Detach**: Removing a database from a project deletes it with the provider and clears its injected environment variables. This is irreversible, so ensure you no longer need the data.
+- **Delete**: Removing a database from a project deletes it with the provider and clears its injected environment variables. This is irreversible, so ensure you no longer need the data.

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

@@ -0,0 +1,142 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Deploy to Mastra platform
+
+[`mastra deploy`](https://mastra.ai/reference/cli/mastra) is the single command for shipping a Mastra application to the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview). One command builds your project, validates it before anything ships, creates the platform project and environment on your first run, deploys, streams build logs, and prints your public URL once the deploy is serving traffic.
+
+```bash
+mastra deploy
+```
+
+> **Note:** This page covers the unified deploy flow. The earlier split commands, [`mastra server deploy`](https://mastra.ai/docs/mastra-platform/server) and [`mastra studio deploy`](https://mastra.ai/docs/mastra-platform/studio), still work but `mastra deploy` is the recommended path.
+
+## Before you begin
+
+You'll need a [Mastra application](https://mastra.ai/guides/getting-started/quickstart) and a [Mastra platform](https://projects.mastra.ai) account. If you're not authenticated, the CLI prompts you to log in on first use.
+
+A local `.env` file is optional. Environment variables stored on the platform are used as-is at deploy time, and managed resources like [hosted databases](https://mastra.ai/docs/mastra-platform/database) inject their own variables. Pass `--env-file` only when you want to layer local values on top.
+
+## Your first deploy
+
+1. From your project directory, run:
+
+   ```bash
+   mastra deploy
+   ```
+
+   On the first run the CLI prompts you to create the platform project (named after your `package.json`) and the `production` environment. Accept the prompts, or pass `--yes` to accept defaults without confirmation.
+
+2. The CLI runs a preflight check before anything ships. Storage that would fall back to a local file path blocks the deploy, because local files don't survive on the platform's ephemeral filesystem:
+
+   ```text
+   [LOCAL_STORAGE_PATH] file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set
+   ```
+
+   Attach a [hosted database](https://mastra.ai/docs/mastra-platform/database) that provides the missing variables:
+
+   ```bash
+   mastra env db create --kind turso
+   ```
+
+   Provisioning takes a few seconds. The database's connection variables are injected into your deploys automatically, with nothing to copy into an `.env` file.
+
+   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), guard it with an environment variable first so the file is only used during local development:
+   >
+   > ```ts
+   > new LibSQLStore({
+   >   // Uses the hosted database when deployed, a local file during development
+   >   url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
+   >   authToken: process.env.TURSO_AUTH_TOKEN,
+   > })
+   > ```
+
+3. Run `mastra deploy` again. Preflight passes, the build uploads, and the CLI streams build logs until the deploy is live. Expect the full build and deploy to take between 30 seconds and a few minutes. The success message prints only when the new version is serving traffic.
+
+4. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
+
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+
+The first deploy writes a `.mastra-project.json` file linking your directory to the platform project. Commit it so later deploys, CI runs, and [`mastra env`](https://mastra.ai/docs/mastra-platform/environments) commands target the same project without extra flags.
+
+## Deploy to another environment
+
+`mastra deploy` targets the `production` environment by default. Pass `--env` to target a different one. If the environment doesn't exist yet, the CLI offers to create it:
+
+```bash
+mastra deploy --env staging
+```
+
+Each environment gets its own URL, its own environment variables, and optionally its own [hosted database](https://mastra.ai/docs/mastra-platform/database). See [Environments](https://mastra.ai/docs/mastra-platform/environments) for the full model.
+
+## Choose a region
+
+Pass `--region` when a deploy creates a new environment to control where it runs. Use the `us` or `eu` shorthand:
+
+```bash
+mastra deploy --env production --region eu
+```
+
+The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically.
+
+## Preflight checks
+
+Preflight validates the built output before anything ships, and only flags issues in your own code:
+
+- **Local storage paths**: A hard block. File-backed storage (for example `file:./mastra.db`) is lost on every deploy. Preflight passes when the path is guarded by an environment variable that is set locally, stored on the platform, or provided by a managed database:
+
+  ```ts
+  import { LibSQLStore } from '@mastra/libsql'
+
+  export const storage = new LibSQLStore({
+    // Uses the hosted database when deployed, a local file during development
+    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
+    authToken: process.env.TURSO_AUTH_TOKEN,
+  })
+  ```
+
+- **Missing environment variables**: A warning for variables your code reads but no source provides. Variables referenced only by library code are excluded.
+
+The recommended response to a preflight block is to fix the cause, usually by attaching a hosted database or storing the variable on the platform. `--skip-preflight` exists as an escape hatch but skips the checks that prevent broken deploys.
+
+Run the checks without deploying:
+
+```bash
+mastra lint --preflight
+```
+
+`mastra lint` only sees your local env files. Variables stored on the platform or injected by managed databases aren't visible to it, so a deploy can pass preflight where lint still reports an error.
+
+## Environment variables
+
+Deploys resolve environment variables from three sources:
+
+- **Managed variables**: Injected by platform resources like hosted databases (for example `TURSO_DATABASE_URL`). The platform defines these, and you can't edit them.
+- **Stored variables**: Saved on the project or environment through the dashboard. Used as-is on every deploy with no local file needed.
+- **Local env files**: An explicit `--env-file`, or ambient `.env` and `.env.local` files, layered on top at deploy time.
+
+```bash
+mastra deploy --env staging --env-file .env.staging
+```
+
+To change variables on a running service without a redeploy, update them in the dashboard and run [`mastra env restart`](https://mastra.ai/reference/cli/mastra).
+
+## Project resolution
+
+Every deploy resolves its target project in this order:
+
+1. The `MASTRA_PROJECT_ID` environment variable
+2. The `--project <name|slug|id>` flag
+3. The `.mastra-project.json` file in the current directory
+
+In CI, set `MASTRA_PROJECT_ID` and `MASTRA_API_TOKEN` and pass `--yes`:
+
+```bash
+mastra deploy --env production --yes
+```
+
+## Related
+
+- [Environments](https://mastra.ai/docs/mastra-platform/environments)
+- [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
+- [`mastra deploy` CLI reference](https://mastra.ai/reference/cli/mastra)
+- [Configuration](https://mastra.ai/docs/mastra-platform/configuration)

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

@@ -0,0 +1,103 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Environments
+
+Every platform project contains one or more environments. An environment is an isolated deployment target with its own URL, its own environment variables, its own deploy history, and optionally its own [hosted database](https://mastra.ai/docs/mastra-platform/database). Use environments to run `production`, `staging`, and preview versions of the same codebase inside a single project.
+
+Your first [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) creates the `production` environment. Create more with the CLI or by deploying to a name that doesn't exist yet.
+
+## Create an environment
+
+Create an environment explicitly:
+
+```bash
+mastra env create staging
+```
+
+Or let a deploy create it, which prompts for confirmation:
+
+```bash
+mastra deploy --env staging
+```
+
+`mastra env create` defaults to the `staging` type. Pass `--type` to set `staging` or `preview` explicitly, and `--region` to choose where the environment runs:
+
+```bash
+mastra env create eu-preview --type preview --region eu
+```
+
+Each project has a single `production` environment, created by your first deploy. The region is fixed at creation. Databases attached to an environment are placed near the environment's region automatically. The number of environments per project depends on your plan.
+
+## List environments
+
+```bash
+mastra env list
+```
+
+The output shows each environment's name, region, active deploy status, and the managed environment variables injected by attached databases. Pass `--json` for machine-readable output in CI.
+
+All `mastra env` commands resolve their project from `MASTRA_PROJECT_ID`, the `--project` flag, or the `.mastra-project.json` file written by your first deploy, in that order. Run them from your project directory and you never need to name the project.
+
+## Environment variables
+
+An environment resolves its variables from three scopes:
+
+- **Managed variables**: Injected by attached [hosted databases](https://mastra.ai/docs/mastra-platform/database) (for example `TURSO_DATABASE_URL`). The platform defines these, and you can't edit them.
+- **Environment-scoped variables**: Stored on one environment through the dashboard. Use these for values that differ between environments, like API keys for staging and production services.
+- **Project-scoped variables**: Stored on the project and shared by all environments.
+
+Environment-scoped and project-scoped variables together are the stored variables described on the [Deploy](https://mastra.ai/docs/mastra-platform/deploy) page.
+
+Variables are applied when a deploy starts. To apply changed variables to a running service without a full redeploy:
+
+```bash
+mastra env restart staging
+```
+
+To see the full set an environment's deploys actually run with — environment-scoped and project-scoped values merged, with managed variables listed by name — pull them into a local env file:
+
+```bash
+mastra env vars pull staging --output .env.staging
+```
+
+Managed variable values are injected at deploy time and never written to the file; they appear as name-only comments.
+
+> **Note:** Environment variables don't override managed database variables. To point an environment at a different database, attach an [environment-scoped database](https://mastra.ai/docs/mastra-platform/database) instead.
+
+## Deploy history
+
+List deploys across all environments, or filter to one:
+
+```bash
+mastra env deploys
+mastra env deploys staging
+```
+
+Each row shows the deploy status, environment, timestamp, and which deploy is currently active. A deploy transitions through **queued → uploading → building → deploying → running**, and the platform reports **running** only when the new version is serving traffic.
+
+## Isolate an environment's data
+
+By default a hosted database attached to the project is shared by all environments. To isolate production data from staging data, attach a separate database to each environment instead:
+
+```bash
+mastra env db create production --kind turso --name my-project-production-db
+mastra env db create staging --kind turso --name my-project-staging-db
+```
+
+Each environment then reads and writes only its own database.
+
+An environment can only use one database per provider. If the project already has a shared project-scoped database of the same provider, attaching an environment-scoped one is rejected with a variable name conflict — delete the shared database with `mastra env db delete` first. Deleting a database destroys it with the provider along with all of its data, so export anything you need to keep. See [Hosted databases](https://mastra.ai/docs/mastra-platform/database) for the full scoping model.
+
+## Delete an environment
+
+```bash
+mastra env delete staging
+```
+
+The CLI asks for confirmation before deleting. Deleting an environment removes its deploys and stored variables.
+
+## Related
+
+- [Deploy](https://mastra.ai/docs/mastra-platform/deploy)
+- [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
+- [`mastra env` CLI reference](https://mastra.ai/reference/cli/mastra)

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

@@ -8,9 +8,9 @@ The [Mastra platform](https://projects.mastra.ai) provides three products for de
 - [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces. Starting with Studio also gives you Observability.
 - [**Server**](https://mastra.ai/docs/mastra-platform/server): A production deployment target that runs your Mastra application as an API server. Starting with Server also gives you Observability.
 
-You can deploy Studio and Server from the CLI or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
+Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy), or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
 
-You can also provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from your project settings to persist your application data with no manual configuration.
+Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`) and provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data with no manual configuration.
 
 ## Get started
 
@@ -20,7 +20,7 @@ Choose the path that matches what you want to do:
 - **Deploy Studio**: Use [Studio](https://mastra.ai/docs/mastra-platform/studio) to host the visual development environment for your team. Start here if you want a shared UI for testing agents, running workflows, and inspecting traces.
 - **Deploy Server**: Use [Server](https://mastra.ai/docs/mastra-platform/server) to run your Mastra application as a production API server. Start here when you’re ready to serve agents, tools, and workflows from the cloud.
 
-## Key Concepts
+## Key concepts
 
 **Projects** are the shared parent entity across all products. A single project can have Observability, a Studio deployment, and a Server deployment. Projects belong to an **Organization**, which is the multi-tenant container for your team.
 
@@ -34,8 +34,8 @@ Your Mastra application is built from three building blocks:
 
 Develop your project locally with [`mastra dev`](https://mastra.ai/reference/cli/mastra) and open [Studio](https://mastra.ai/docs/studio/overview) to test your agents, workflows, and tools in a visual environment.
 
-Once you're ready to deploy your application to production, use [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra) and [`mastra server deploy`](https://mastra.ai/reference/cli/mastra) to push your application to the cloud.
+Once you're ready to deploy your application to production, run [`mastra deploy`](https://mastra.ai/reference/cli/mastra) to push your application to the cloud.
 
-Follow the [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio) and [Server on Mastra platform](https://mastra.ai/docs/mastra-platform/server) docs for step-by-step instructions.
+Follow the [Deploy](https://mastra.ai/docs/mastra-platform/deploy) docs for step-by-step instructions.
 
 If you host your Mastra application on your own infrastructure, you can still send observability data to Mastra platform using the [MastraPlatformExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform).

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

@@ -6,6 +6,8 @@ Server on Mastra platform is a production deployment target that runs your Mastr
 
 You get a stable API endpoint, environment variable management, custom domain support, and deploy history out of the box.
 
+> **Note:** `mastra server deploy` is the earlier split deploy path. New projects should use the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command, which adds preflight validation, environments, and CLI-managed databases.
+
 > **Note:** Server deploy provisions hosted storage automatically. If you override storage with [LibSQLStore](https://mastra.ai/reference/storage/libsql) and a file URL, switch to a remotely hosted database because Mastra platform uses an ephemeral filesystem.
 
 ## Quickstart

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

@@ -2,10 +2,12 @@
 
 # Studio on Mastra platform
 
-Studio on Mastra platform is a hosted visual environment for testing agents, running workflows, and inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.
+Studio on Mastra platform is a hosted visual workspace for testing agents, running workflows, and inspecting traces. Use it when you want to share Studio with your team without hosting the Studio UI yourself.
 
 You can deploy Studio from the CLI as shown below, or link a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
 
+> **Note:** `mastra studio deploy` is the earlier split deploy path. New projects should use the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command, which adds preflight validation, environments, and CLI-managed databases.
+
 ## Quickstart
 
 1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
@@ -56,7 +58,7 @@ See the [`mastra studio deploy` CLI reference](https://mastra.ai/reference/cli/m
 
 ## Environment files
 
-The deploy bundles environment variables from a `.env` or `.env.*` file in the project directory. If no env file is present, the deploy errors with `No env file found for deploy.` after the build step. Add at least an empty `.env` file before running the command.
+A local env file is optional. When a `.env` or `.env.*` file is present in the project directory, the deploy bundles its environment variables.
 
 When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass `--env-file`:
 
@@ -64,7 +66,7 @@ When multiple env files are present, the CLI prompts you to pick one. To select
 mastra studio deploy --env-file .env.production --yes
 ```
 
-This is also how you target multiple environments from a single codebase: maintain one env file per environment, such as `.env.staging` and `.env.production`, and pass the right one to each deploy. Each environment still requires its own Mastra platform project. See [Configuration](https://mastra.ai/docs/mastra-platform/configuration) for the multi-environment pattern.
+To run the same codebase across `production` and `staging`, use the unified [`mastra deploy --env`](https://mastra.ai/docs/mastra-platform/deploy) command instead. [Environments](https://mastra.ai/docs/mastra-platform/environments) replace the earlier pattern of one project per environment.
 
 ## Create a new project non-interactively
 

package/.docs/guides/guide/chef-michel.md

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# How to build an AI chef assistant
+# Building an AI chef assistant
 
 In this guide, you'll create a "Chef Assistant" agent that helps users cook meals with available ingredients.
 

package/.docs/guides/guide/coding-agent.md

@@ -0,0 +1,392 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Building a coding agent
+
+In this guide, you'll build a small coding-agent application in the same category as Mastra Code, Claude Code, or Codex. You'll create the coding agent with `buildBasePrompt()` and `createCodingAgent()`, wrap it in an `AgentController` for interactive sessions and tool approvals, and run the controller in a terminal UI built with pi-tui.
+
+The video below shows the coding agent you'll build in action.
+
+## Prerequisites
+
+- Node.js `v22.19.0` or later installed
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project. Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) if needed.
+
+## Install the terminal dependencies
+
+Install [pi-tui](https://github.com/earendil-works/pi/tree/main/packages/tui) and `tsx`:
+
+**npm**:
+
+```bash
+npm install @earendil-works/pi-tui
+npm install --save-dev tsx
+```
+
+**pnpm**:
+
+```bash
+pnpm add @earendil-works/pi-tui
+pnpm add --save-dev tsx
+```
+
+**Yarn**:
+
+```bash
+yarn add @earendil-works/pi-tui
+yarn add --dev tsx
+```
+
+**Bun**:
+
+```bash
+bun add @earendil-works/pi-tui
+bun add --dev tsx
+```
+
+pi-tui provides the terminal renderer and input editor. `tsx` runs the TypeScript entry point directly.
+
+## Create the coding agent
+
+Create `src/mastra/agents/coding-agent.ts`. The prompt describes the current project and maps the prompt's generic tool names to the tools supplied by the default workspace.
+
+```typescript
+import { basename } from 'node:path'
+import { buildBasePrompt, createCodingAgent } from '@mastra/core/coding-agent'
+
+export const projectPath = process.cwd()
+const model = 'openai/gpt-5.5'
+
+const instructions = buildBasePrompt({
+  projectPath,
+  projectName: basename(projectPath),
+  platform: process.platform,
+  date: new Date().toISOString().slice(0, 10),
+  mode: 'build',
+  modelId: model,
+  productName: 'My Coding Agent',
+  coAuthorName: 'My Coding Agent',
+  coAuthorEmail: 'coding-agent@example.com',
+  toolGuidance: `# Workspace tools
+- Use mastra_workspace_read_file for view.
+- Use mastra_workspace_list_files for find_files.
+- Use mastra_workspace_grep for search_content.
+- Use mastra_workspace_execute_command for execute_command.
+- Use mastra_workspace_write_file, mastra_workspace_edit_file, and mastra_workspace_file_stat for writing, editing, and inspecting file metadata.
+- Use only the workspace tools provided to you. Do not attempt unavailable capabilities.`,
+})
+
+export const codingAgent = createCodingAgent({
+  id: 'coding-agent',
+  name: 'Coding Agent',
+  model,
+  instructions,
+  basePath: projectPath,
+})
+```
+
+Replace the branding values with the name and co-author details for your agent. `createCodingAgent()` supplies a local filesystem and sandbox workspace, along with defaults for recovering from transient provider errors. The `basePath` scopes the filesystem tools and sets the initial working directory for commands. Any configuration you pass to the factory takes precedence over its defaults.
+
+The default local sandbox runs commands directly on the host without isolation, so `basePath` isn't an operating-system security boundary. This example adds per-tool-call approval in the terminal, but you should still run it only against a trusted local project.
+
+## Register the coding agent
+
+Register the returned agent like any other Mastra agent in `src/mastra/index.ts`. Registration also makes the underlying agent available in Studio and through the Mastra server.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { codingAgent } from './agents/coding-agent'
+
+export const mastra = new Mastra({
+  agents: { codingAgent },
+})
+```
+
+## Test the coding agent
+
+Before adding the terminal interface, verify the underlying agent in Studio. When the development server starts, its working directory is `src/mastra/public`, so add a non-sensitive file there for the agent to inspect:
+
+```md
+# Project notes
+
+Name: Acme support portal
+Status: In development
+Owner: Platform team
+```
+
+Start the development server:
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Open [Studio](https://mastra.ai/docs/studio/overview), select **Coding Agent**, and enter:
+
+```text
+Inspect project-notes.md and report the project name, status, and owner. Do not modify files.
+```
+
+The response should identify the Acme support portal, its development status, and the Platform team without changing the file. Model wording may vary.
+
+## Create the agent controller
+
+Create `src/mastra/coding-agent-controller.ts`. The controller owns the interactive session, exposes UI events, and pauses workspace tools for approval.
+
+```typescript
+import { AgentController } from '@mastra/core/agent-controller'
+import { codingAgent, projectPath } from './agents/coding-agent'
+
+export async function createCodingAgentSession() {
+  const workspace = await codingAgent.getWorkspace()
+
+  if (!workspace) {
+    throw new Error('The coding agent requires a workspace.')
+  }
+
+  const controller = new AgentController({
+    id: 'coding-agent-controller',
+    agent: codingAgent,
+    workspace,
+    modes: [{ id: 'build', name: 'Build', metadata: { default: true } }],
+    disableBuiltinTools: [
+      'ask_user',
+      'submit_plan',
+      'task_write',
+      'task_update',
+      'task_complete',
+      'task_check',
+      'subagent',
+    ],
+  })
+
+  await controller.init()
+
+  const session = await controller.createSession({
+    id: 'local-session',
+    ownerId: 'local-user',
+    resourceId: projectPath,
+  })
+
+  return { controller, session }
+}
+```
+
+This example uses one mode and disables the controller's additional built-in tools so the introductory UI can focus on workspace execution. This is a tutorial simplification, not a production recommendation. In a production application, enable the built-in tools your product needs and implement their UI flows: interactive tools such as `ask_user` and `submit_plan` suspend until your interface resumes them, while task and subagent tools have their own lifecycle events. See [tool approvals and suspensions](https://mastra.ai/docs/agent-controller/tool-approvals).
+
+The example also omits storage, so the conversation lasts only for the current process. You can add storage later when you want to resume sessions.
+
+## Build the terminal UI
+
+Create `src/coding-agent-tui.ts`. The UI renders assistant message updates, shows tool activity, and asks the user to approve or decline each workspace tool call.
+
+```typescript
+import { pathToFileURL } from 'node:url'
+import {
+  Editor,
+  matchesKey,
+  ProcessTerminal,
+  Text,
+  TUI,
+  type EditorTheme,
+  type Terminal,
+} from '@earendil-works/pi-tui'
+import { createCodingAgentSession } from './mastra/coding-agent-controller'
+
+const plain = (text: string) => text
+const editorTheme: EditorTheme = {
+  borderColor: plain,
+  selectList: {
+    selectedPrefix: plain,
+    selectedText: plain,
+    description: plain,
+    scrollInfo: plain,
+    noMatch: plain,
+  },
+}
+
+function getText(message: { content: Array<{ type: string; text?: string }> }) {
+  return message.content
+    .filter(part => part.type === 'text')
+    .map(part => part.text ?? '')
+    .join('')
+}
+
+export async function startCodingAgentTui(terminal: Terminal = new ProcessTerminal()) {
+  const { controller, session } = await createCodingAgentSession()
+  const tui = new TUI(terminal)
+  const output = new Text('Ask me to inspect or change this project.', 1, 0)
+  const editor = new Editor(tui, editorTheme)
+
+  let busy = false
+  let pendingApproval: { toolCallId: string; toolName: string } | undefined
+
+  const showError = (error: unknown) => {
+    output.setText(`Error: ${error instanceof Error ? error.message : String(error)}`)
+    busy = false
+    pendingApproval = undefined
+    tui.requestRender()
+  }
+
+  const unsubscribe = session.subscribe(event => {
+    if (event.type === 'message_update' && event.message.role === 'assistant') {
+      output.setText(getText(event.message))
+    } else if (event.type === 'tool_start') {
+      output.setText(`Running ${event.toolName}...`)
+    } else if (event.type === 'tool_approval_required') {
+      pendingApproval = { toolCallId: event.toolCallId, toolName: event.toolName }
+      output.setText(`Allow ${event.toolName}? Enter y or n.`)
+    } else if (event.type === 'agent_end') {
+      busy = false
+    } else if (event.type === 'error') {
+      showError(event.error)
+      return
+    }
+
+    tui.requestRender()
+  })
+
+  editor.onSubmit = value => {
+    if (pendingApproval) {
+      const answer = value.trim().toLowerCase()
+      if (answer !== 'y' && answer !== 'n') {
+        output.setText(`Allow ${pendingApproval.toolName}? Enter y or n.`)
+        tui.requestRender()
+        return
+      }
+
+      const approval = pendingApproval
+      pendingApproval = undefined
+      session.respondToToolApproval({
+        toolCallId: approval.toolCallId,
+        decision: answer === 'y' ? 'approve' : 'decline',
+      })
+      return
+    }
+
+    if (busy || !value.trim()) return
+
+    busy = true
+    output.setText('Thinking...')
+    tui.requestRender()
+    void session.sendMessage({ content: value.trim() }).catch(showError)
+  }
+
+  tui.addChild(new Text('My Coding Agent', 1, 0))
+  tui.addChild(output)
+  tui.addChild(editor)
+  tui.setFocus(editor)
+
+  let stopPromise: Promise<void> | undefined
+  let removeInputListener = () => {}
+
+  const stop = () => {
+    stopPromise ??= (async () => {
+      process.off('SIGINT', handleExit)
+      removeInputListener()
+      session.abort()
+      unsubscribe()
+      tui.stop()
+      await controller.destroy()
+    })()
+    return stopPromise
+  }
+
+  const handleExit = () => {
+    void stop().catch(error => {
+      console.error(error)
+      process.exitCode = 1
+    })
+  }
+
+  removeInputListener = tui.addInputListener(data => {
+    if (!matchesKey(data, 'ctrl+c')) return
+    handleExit()
+    return { consume: true }
+  })
+  process.once('SIGINT', handleExit)
+  tui.start()
+
+  return { stop }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await startCodingAgentTui()
+}
+```
+
+The optional `Terminal` parameter supports automated tests while using `ProcessTerminal` during normal execution. The UI intentionally renders only the latest response; the `Session` still maintains the conversation context for follow-up prompts.
+
+## Run the coding agent
+
+Start the terminal application from the project root so `process.cwd()` points to the project you want the agent to use:
+
+**npm**:
+
+```bash
+npx tsx src/coding-agent-tui.ts
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx tsx src/coding-agent-tui.ts
+```
+
+**Yarn**:
+
+```bash
+yarn dlx tsx src/coding-agent-tui.ts
+```
+
+**Bun**:
+
+```bash
+bun x tsx src/coding-agent-tui.ts
+```
+
+Enter this prompt:
+
+```text
+Inspect package.json and report the package name and available scripts. Do not modify files.
+```
+
+When the controller asks whether to allow `mastra_workspace_read_file`, enter `y`. The agent reads `package.json` and reports what it finds. Model wording varies, but the response should include the package name and its scripts without changing the file.
+
+Press **Ctrl+C** to close the application and destroy the controller.
+
+## Next steps
+
+You can extend this foundation to:
+
+- Add storage to persist and resume controller sessions
+- Add more modes with different instructions and workspace-tool allowlists
+- Replace the latest-response component with a transcript that renders tool calls and results
+- Add sandbox isolation before accepting untrusted prompts or distributing the application
+
+Learn more:
+
+- [`createCodingAgent()` reference](https://mastra.ai/reference/coding-agent/create-coding-agent)
+- [`buildBasePrompt()` reference](https://mastra.ai/reference/coding-agent/build-base-prompt)
+- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
+- [`AgentController` reference](https://mastra.ai/reference/agent-controller/agent-controller-class)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/guides/migrations/mastra-cloud.md

@@ -271,7 +271,7 @@ mastra studio deploy
 
 The CLI builds your project, uploads the artifact, and deploys it. On first deploy, a `.mastra-project.json` file is created to link your local project to the platform. Commit this file to your repository.
 
-The deploy requires a `.env` or `.env.*` file in the project directory. If none exists the CLI errors with `No env file found for deploy.` after the build completes — add at least an empty `.env` before running the command.
+A local env file is optional. When a `.env` or `.env.*` file is present in the project directory, the deploy bundles its environment variables.
 
 To create a new platform project in one non-interactive step (instead of running `mastra studio projects create` separately), pass a name with `--project` and accept defaults with `--yes`:
 
@@ -283,21 +283,14 @@ See [Studio deployment](https://mastra.ai/docs/studio/deployment) for details.
 
 ### Multiple environments
 
-Mastra platform projects don't have a built-in concept of named environments (for example `staging` vs `production`). To deploy the same codebase to multiple environments, create one project per environment and pair each deploy with the matching env file using `--env-file`.
-
-The pattern below uses one `.env.<env>` file per environment, deploys to a project named `my-app-<env>`, and overrides `.mastra-project.json` per deploy with `MASTRA_ORG_ID` and `MASTRA_PROJECT_ID`:
+A single Mastra platform project runs the same codebase across multiple named [environments](https://mastra.ai/docs/mastra-platform/environments), such as `production` and `staging`. Deploy to each with the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command:
 
 ```bash
-# First deploy of each environment — creates the project
-mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
-mastra studio deploy --project "my-app-production" --env-file .env.production --yes
-
-# Subsequent deploys (CI/CD) — target the existing project
-MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --yes
-MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
+mastra deploy --env production --yes
+mastra deploy --env staging --env-file .env.staging --yes
 ```
 
-Each environment ends up with its own Studio URL and its own observability data. Send `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` per environment so `MastraPlatformExporter` routes traces to the correct project.
+Each environment gets its own URL, its own environment variables, and its own deploy history.
 
 ## Deploy Server (optional)
 

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

@@ -342,13 +342,28 @@ mastra env restart <env>
 
 `<env>` can be an environment name, slug, or ID. Fails with a conflict error if the environment has never been deployed.
 
+### `mastra env vars pull`
+
+Pulls an environment's env vars into a local env file (default: `.env`). The file contains the merged set a deploy actually runs with: vars stored on the environment (for example, added in the dashboard's environment editor) plus project-level vars, with project values winning on conflict. Managed vars injected by attached databases are listed as comments (names only) since their values are platform-managed secrets.
+
+```bash
+mastra env vars pull
+mastra env vars pull <env> --output .env.staging
+```
+
+`<env>` can be an environment name, slug, or ID, and can be omitted when the project has exactly one environment. The file is written with `0600` permissions.
+
+#### `-o, --output`
+
+File to write. Defaults to `.env`.
+
 ### `mastra env db`
 
 Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.
 
 A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Pass the environment argument to work with environment-scoped databases; omit it for shared databases.
 
-Creating and detaching databases requires the `admin` role in the organization.
+Creating and deleting databases requires the `admin` role in the organization.
 
 ### `mastra env db list`
 
@@ -412,12 +427,12 @@ Print secret connection values instead of masking them.
 
 Emit machine-readable JSON. Secret values are masked unless `--show-secrets` is passed.
 
-### `mastra env db detach`
+### `mastra env db delete`
 
-Detaches a database from the project. The CLI prompts for confirmation unless `--yes` is passed. After detaching, deploys no longer receive the database's env vars.
+Permanently deletes a database with the provider, including all of its data. This cannot be undone. The CLI prompts for confirmation unless `--yes` is passed. After deletion, deploys no longer receive the database's env vars.
 
 ```bash
-mastra env db detach <database>
+mastra env db delete <database>
 ```
 
 #### `-y, --yes`

package/.docs/reference/pubsub/redis-streams.md

@@ -63,6 +63,8 @@ export const mastra = new Mastra({
 
 **maxStreamLength** (`number`): Approximate maximum number of entries kept per stream. Set to 0 to disable trimming. (Default: `10000`)
 
+**streamIdleTtlMs** (`number`): Idle expiry in milliseconds: a sliding TTL refreshed on every write (publish, nack retry, group re-creation). Each write resets it, so an actively-written stream never expires mid-flight; a stream left idle for the full duration is deleted by Redis automatically. Note that only writes refresh the TTL — a consumer slowly draining a backlog does not — so set it well above the longest expected gap between writes on a live topic. This is a backstop, not the primary cleanup — clearTopic handles normal end-of-lifecycle deletion; this only bounds memory for streams that never reach a clearTopic call (e.g. a crashed run). Must be a non-negative integer. Defaults to 0 (disabled). (Default: `0`)
+
 **reclaimIntervalMs** (`number`): How often, in milliseconds, a subscription reclaims events that an earlier consumer read but never acknowledged. Set to 0 to disable. (Default: `30000`)
 
 **reclaimIdleMs** (`number`): Minimum idle time, in milliseconds, before a pending event is eligible for reclaim. Keep this well above typical processing time to avoid double delivery. (Default: `60000`)
@@ -97,6 +99,16 @@ Waits for in-flight publishes to complete.
 await pubsub.flush()
 ```
 
+### `clearTopic(topic)`
+
+Deletes a topic's stream and every consumer group on it, freeing the memory a finished topic would otherwise hold. The durable-agent runtime calls this automatically when a run's cleanup fires; call it yourself only once nothing will read the topic again. It's best-effort and never throws — failures are logged at warn level. A subscriber still attached when the stream is deleted recovers on its own but misses the deleted entries.
+
+Automatic cleanup requires `@mastra/core` and `@mastra/redis-streams` versions that both support `clearTopic`: the runtime routes the call through its caching layer, so upgrade the two packages together to get end-of-run stream deletion.
+
+```typescript
+await pubsub.clearTopic('workflow.events.run-123')
+```
+
 ### `close()`
 
 Closes the Redis connections and stops all subscriptions. Call this during graceful shutdown.

package/.docs/reference/voice/speechify.md

@@ -15,15 +15,15 @@ const voice = new SpeechifyVoice()
 // Initialize with custom configuration
 const voice = new SpeechifyVoice({
   speechModel: {
-    name: 'simba-english',
+    name: 'simba-3.2',
     apiKey: 'your-api-key',
   },
-  speaker: 'george', // Default voice
+  speaker: 'harper_32', // Default voice (simba-3.2 serves the curated Simba 3 voices only)
 })
 
 // Convert text to speech
 const audioStream = await voice.speak('Hello, world!', {
-  speaker: 'henry', // Override default voice
+  speaker: 'imogen_32', // Override default voice
 })
 ```
 
@@ -31,11 +31,11 @@ const audioStream = await voice.speak('Hello, world!', {
 
 **speechModel** (`SpeechifyConfig`): Configuration for text-to-speech functionality (Default: `{ name: 'simba-english' }`)
 
-**speechModel.name** (`VoiceModelName`): The Speechify model to use
+**speechModel.name** (`SpeechifyModel`): The Speechify model to use ('simba-3.2', 'simba-3.0', 'simba-english', or 'simba-multilingual')
 
 **speechModel.apiKey** (`string`): Speechify API key. Falls back to SPEECHIFY\_API\_KEY environment variable
 
-**speaker** (`SpeechifyVoiceId`): Default voice ID to use for speech synthesis (Default: `'george'`)
+**speaker** (`SpeechifyVoiceId`): Default voice ID to use for speech synthesis. The Simba 3 models serve a curated voice set only (harper\_32, imogen\_32, ...); the classic catalog voices (george, henry, ...) work with simba-english and simba-multilingual (Default: `'harper_32' for Simba 3 models, otherwise 'george'`)
 
 ## Methods
 
@@ -49,7 +49,7 @@ Converts text to speech using the configured speech model and voice.
 
 **options.speaker** (`string`): Override the default speaker for this request
 
-**options.model** (`VoiceModelName`): Override the default model for this request
+**options.model** (`SpeechifyModel`): Override the default model for this request
 
 Returns: `Promise<NodeJS.ReadableStream>`
 
@@ -73,5 +73,9 @@ This method isn't supported by Speechify and will throw an error. Speechify does
 
 - Speechify requires an API key for authentication
 - The default model is 'simba-english'
+- 'simba-3.2' is Speechify's latest streaming model with the lowest latency and richest expressivity, and the recommended model for English
+- 'simba-3.2' and 'simba-3.0' are currently English only; use 'simba-multilingual' for non-English or mixed-language input
+- 'simba-3.2' and 'simba-3.0' serve a curated voice set only: 'beatrice\_32', 'dominic\_32', 'edmund\_32', 'geffen\_32', 'harper\_32', 'hugh\_32', 'imogen\_32', 'wyatt\_32'. Classic catalog voices such as 'george' return an error on these models
+- The default speaker follows the configured model: 'harper\_32' for the Simba 3 models, otherwise 'george'
 - Speech-to-text functionality isn't supported
 - Additional audio stream options can be passed through the speak() method's options parameter

package/.docs/reference/workspace/e2b-sandbox.md

@@ -247,6 +247,25 @@ const workspace = new Workspace({
 
 This is optional—`gcsfuse` is installed automatically at mount time if not present.
 
+## Using with Code Mode
+
+[Code Mode](https://mastra.ai/docs/agents/code-mode) lets an agent write a single TypeScript program that orchestrates its tools. Because E2B runs that program in a remote micro-VM, it needs a transport that writes the program into the sandbox filesystem rather than the host. `@mastra/e2b` ships `E2BCodeModeTransport` for this—pass it as the second argument to `createCodeMode`:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'
+
+const { tool, instructions } = createCodeMode(
+  {
+    tools: { getWeather, getForecast },
+    sandbox: new E2BSandbox({ timeout: 60_000 }),
+  },
+  new E2BCodeModeTransport(),
+)
+```
+
+`E2BCodeModeTransport` auto-starts the sandbox if it isn't running, strips TypeScript on the host with esbuild (so it works regardless of the sandbox's Node version), runs `node` inside the VM, and cleans up the program files afterwards. The default `StdioCodeModeTransport` from `@mastra/core` only works with sandboxes that share the host filesystem, such as `LocalSandbox`.
+
 ## Related
 
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.7-alpha.20
+
+### Patch Changes
+
+- Updated dependencies [[`4adc391`](https://github.com/mastra-ai/mastra/commit/4adc3911075249c352bb4832d2471922826344de), [`b486abf`](https://github.com/mastra-ai/mastra/commit/b486abfa2a7528c6f527e4015c819ea9fa54aaad)]:
+  - @mastra/core@1.51.0-alpha.10
+
+## 1.2.7-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`edce8d2`](https://github.com/mastra-ai/mastra/commit/edce8d2769f19e27a05737c627af2d765472a4f8)]:
+  - @mastra/core@1.51.0-alpha.9
+
 ## 1.2.7-alpha.17
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.7-alpha.18",
+  "version": "1.2.7-alpha.20",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.51.0-alpha.8",
-    "@mastra/mcp": "^1.14.0-alpha.0"
+    "@mastra/mcp": "^1.14.0-alpha.0",
+    "@mastra/core": "1.51.0-alpha.10"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
+    "@internal/lint": "0.0.113",
     "@internal/types-builder": "0.0.88",
-    "@mastra/core": "1.51.0-alpha.8",
-    "@internal/lint": "0.0.113"
+    "@mastra/core": "1.51.0-alpha.10"
   },
   "homepage": "https://mastra.ai",
   "repository": {