@mastra/mcp-docs-server 1.2.8-alpha.9 → 1.2.9-alpha.0

package/.docs/docs/deployment/monorepo.md

@@ -97,6 +97,8 @@ export const mastra = new Mastra({
 })
 ```
 
+Keep `bundler` as a direct property in the object passed to `new Mastra()`. See [build-time configuration](https://mastra.ai/docs/deployment/mastra-server) for the supported entry-file shape.
+
 ## Environment variables
 
 Store `.env` files in the Mastra application directory (e.g., `apps/api/.env`), not the monorepo root.

package/.docs/docs/deployment/overview.md

@@ -51,6 +51,12 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Netlify](https://mastra.ai/guides/deployment/netlify)
 - [Vercel](https://mastra.ai/guides/deployment/vercel)
 
+### Sandbox
+
+Deploy a Mastra server into an ephemeral workspace sandbox (such as Vercel Sandbox or E2B) and get a live public URL in seconds.
+
+Use this option for instant previews, deploys from your CI pipeline, verifying agent-built apps, or running untrusted per-user instances. Read the [sandbox deployment guide](https://mastra.ai/docs/deployment/sandbox).
+
 ### Web Framework
 
 When Mastra is integrated with a web framework, it deploys alongside your application using the framework's standard deployment process. The guides below cover framework-specific configuration requirements for deployment.

package/.docs/docs/deployment/sandbox.md

@@ -0,0 +1,277 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Deploy to a sandbox
+
+`@mastra/deployer-sandbox` deploys a full Mastra server, including Studio, into an ephemeral workspace sandbox and returns a live public URL. Repeat deployments can finish faster because the deployer skips dependency installation.
+
+Use sandbox deployments for:
+
+- Agent-built apps: An agent generates a Mastra project and deploys it to verify the result.
+- Continuous integration (CI): Spin up a real server for checks, then tear it down.
+- Instant previews: Share a working agent with your team before merging.
+- Multi-tenant untrusted code: Run per-user Mastra instances isolated from your infrastructure.
+
+Sandboxes have provider-enforced runtime caps and expire. For production hosting, see the [deployment overview](https://mastra.ai/docs/deployment/overview).
+
+## Supported sandboxes
+
+The deployer works with any workspace sandbox that supports networking (public port URLs):
+
+- [Vercel Sandbox](https://mastra.ai/reference/workspace/vercel-sandbox) (`@mastra/vercel`)
+- [E2B](https://mastra.ai/reference/workspace/e2b-sandbox) (`@mastra/e2b`)
+- [Daytona](https://mastra.ai/reference/workspace/daytona-sandbox) (`@mastra/daytona`)
+
+Provider authors can add support by implementing the optional `networking` capability on [`WorkspaceSandbox`](https://mastra.ai/reference/workspace/sandbox).
+
+## Quickstart
+
+Install the deployer and a sandbox provider of your choice. This example uses Vercel Sandbox:
+
+**npm**:
+
+```bash
+npm install @mastra/deployer-sandbox @mastra/vercel
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/deployer-sandbox @mastra/vercel
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/deployer-sandbox @mastra/vercel
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/deployer-sandbox @mastra/vercel
+```
+
+Configure the deployer in your `src/mastra/index.ts` file. The `sandboxName` identifies the deployment, so subsequent deployments with the same name reuse the existing sandbox.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { SandboxDeployer } from '@mastra/deployer-sandbox'
+import { VercelSandbox } from '@mastra/vercel'
+
+export const mastra = new Mastra({
+  deployer: new SandboxDeployer({
+    sandbox: new VercelSandbox({
+      sandboxName: 'my-preview',
+      timeout: 3_600_000, // 1 hour
+      ports: [4111],
+    }),
+  }),
+})
+```
+
+Build and deploy in one command:
+
+```bash
+mastra build
+```
+
+When a `SandboxDeployer()` is configured, `mastra build` bundles your project and deploys it into the sandbox. The deploy prints the API and Studio URLs and writes a `sandbox-deployment.json` manifest into `.mastra/output`:
+
+```text
+API:    https://<sandbox-id>-4111.vercel.run/api
+Studio: https://<sandbox-id>-4111.vercel.run
+```
+
+The manifest includes `expiresAt` when the sandbox provider reports an expiration time. Redeploys to the same sandbox skip the dependency install when the install inputs (`package.json`, bundled lockfiles, and the install command) are unchanged.
+
+### Using E2B
+
+For E2B, the `id` identifies the deployment, so subsequent deployments with the same value reconnect to the existing sandbox, whether it's running or paused.
+
+```typescript
+import { SandboxDeployer } from '@mastra/deployer-sandbox'
+import { E2BSandbox } from '@mastra/e2b'
+
+const deployer = new SandboxDeployer({
+  sandbox: new E2BSandbox({
+    id: 'my-preview',
+    template: 'base',
+    timeout: 3_600_000, // 1 hour
+  }),
+})
+```
+
+Pass `template: 'base'` unless you need filesystem mounts; without it, the provider builds a custom Filesystem in Userspace (FUSE) template on first use. E2B pauses instead of stopping: `stop()` snapshots the whole virtual machine (VM), including memory and running processes. When a paused sandbox wakes, the Mastra server resumes where it left off, and there's no relaunch step like on Vercel.
+
+### Using Daytona
+
+For Daytona, the `id` identifies the deployment, so subsequent deployments with the same value reconnect to the existing sandbox. Set `public: true` to make the preview URL accessible without a token.
+
+```typescript
+import { SandboxDeployer } from '@mastra/deployer-sandbox'
+import { DaytonaSandbox } from '@mastra/daytona'
+
+const deployer = new SandboxDeployer({
+  sandbox: new DaytonaSandbox({
+    id: 'my-preview',
+    public: true,
+    autoStopInterval: 30, // minutes
+  }),
+})
+```
+
+Stopping a Daytona sandbox persists its filesystem but not running processes, so waking works like Vercel: the resolver relaunches the server on `wake: true`.
+
+## Deploying programmatically
+
+`deployToSandbox()` deploys a prebuilt output directory without the bundler. Unlike `SandboxDeployer()`, it doesn't include Studio unless you pass `studio: true`. Use it in CI or from agent code:
+
+```typescript
+import { deployToSandbox } from '@mastra/deployer-sandbox'
+import { VercelSandbox } from '@mastra/vercel'
+
+const deployment = await deployToSandbox({
+  sandbox: new VercelSandbox({ sandboxName: 'ci-smoke', ports: [4111] }),
+  dir: '.mastra/output',
+})
+
+console.info(deployment.url) // https://<sandbox-id>-4111.vercel.run
+await deployment.logs() // tail the server log
+await deployment.stop() // stop the sandbox (resumable)
+await deployment.destroy() // permanently delete the sandbox
+```
+
+## Lifecycle
+
+### Managing a deployment
+
+Use the server-only `getDeployment()` export from `@mastra/deployer-sandbox/client` to retrieve an existing deployment. It identifies the sandbox through provider-specific configuration, such as a Vercel `sandboxName` or an E2B or Daytona `id`. The lookup isn't tied to the process that created the deployment, so you can use it from another server-side service or in CI.
+
+```typescript
+import { getDeployment } from '@mastra/deployer-sandbox/client'
+import { VercelSandbox } from '@mastra/vercel'
+
+const deployment = await getDeployment({
+  sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+  port: 4111,
+})
+
+console.info(deployment.status, deployment.url)
+await deployment.logs() // tail the server log
+await deployment.stop() // stop the sandbox (resumable)
+await deployment.destroy() // permanently delete the sandbox
+```
+
+Pass `wake: true` to resume a stopped sandbox before returning. The server is relaunched only if it isn't healthy after the resume. Provider tooling works too, for example `vercel sandbox ls`, `vercel sandbox stop`, and `vercel sandbox rm`.
+
+### Expiry and URLs
+
+Sandboxes expire according to the provider's runtime limits. When the provider reports an expiration time, the deploy logs it and `deployment.expiresAt` exposes it programmatically.
+
+Sandbox URLs can change when a sandbox stops and resumes. Treat the URL as plumbing and the sandbox identity (for example, the `sandboxName`) as the stable handle. The routing tiers below deal with URL rotation.
+
+## Routing tiers
+
+### Tier 1: Direct URL
+
+Use the printed URL directly for development, demos, and CI where a fresh URL per deploy is acceptable.
+
+### Tier 2: Resolve at runtime
+
+`getDeployment()` resolves the current URL at runtime, so consumers never hold a stale URL. Any server that knows the sandbox name can resolve it, including one in a different codebase than the Mastra project:
+
+```typescript
+import { getDeployment } from '@mastra/deployer-sandbox/client'
+import { VercelSandbox } from '@mastra/vercel'
+
+const deployment = await getDeployment({
+  sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+  wake: true,
+})
+
+console.info(deployment.url, deployment.status)
+```
+
+With `wake: false` (the default) the sandbox isn't started and you get `{ url, status }` to act on. Resolving the URL, `stop()`, and `destroy()` attach to the existing sandbox by name without resuming it, so lifecycle operations on a stopped sandbox never wake it or start billing. With `wake: true` the sandbox resumes and the server is relaunched if it isn't answering. Whether a relaunch is needed depends on the provider: Vercel and Daytona restore the filesystem but not running processes, while E2B resumes the whole VM including the server process.
+
+> **Warning:** `@mastra/deployer-sandbox/client` is server-only. Resolving a sandbox uses provider credentials that must never reach the browser. The module throws if imported in a browser context.
+
+### Tier 3: Stable URL for end users
+
+Give end users a stable URL on your own domain and forward to the sandbox server-side, using either a route handler proxy or an Edge Config alias.
+
+The example below shows a Vercel & Next.js setup, but the concept applies to any server-side framework or provider that can forward requests.
+
+- **Route handler proxy.** `createSandboxHandler()` caches the sandbox URL and re-resolves after a connection-level failure, which covers URL rotation and cold wakes:
+
+  ```typescript
+  import { createSandboxHandler, getDeployment } from '@mastra/deployer-sandbox/client'
+  import { VercelSandbox } from '@mastra/vercel'
+
+  const handler = createSandboxHandler({
+    resolve: async () => {
+      const deployment = await getDeployment({
+        sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+        wake: true,
+      })
+      return deployment.url!
+    },
+  })
+
+  export { handler as GET, handler as POST }
+  ```
+
+- **Edge Config alias.** Set the `alias` option on the deployer to keep a [Vercel Edge Config](https://vercel.com/docs/edge-config) item pointed at the current URL on every deploy:
+
+  ```typescript
+  const deployer = new SandboxDeployer({
+    sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+    alias: { edgeConfigId: 'ecfg_...', key: 'my-preview', token: process.env.VERCEL_TOKEN! },
+  })
+  ```
+
+  Then rewrite requests in Next.js middleware with `createSandboxProxy()`:
+
+  ```typescript
+  import { createSandboxProxy } from '@mastra/deployer-sandbox/client'
+
+  export const middleware = createSandboxProxy({ key: 'my-preview' })
+  export const config = { matcher: '/api/:path*' }
+  ```
+
+## CI example
+
+Deploy a preview on every pull request:
+
+```yaml
+name: Sandbox preview
+on: pull_request
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npx mastra build
+      - run: curl --fail "$(jq -r .url .mastra/output/sandbox-deployment.json)/api"
+```
+
+## Security
+
+- The sandbox URL is public. Anyone with the URL can reach your Mastra server, including Studio. Enable [server auth](https://mastra.ai/docs/server/auth) for anything beyond throwaway previews.
+- Environment variables from your `.env` files are injected into the remote sandbox VM so the server can run. The deploy logs a warning when this happens. Don't deploy secrets you wouldn't put on a shared preview server.
+- To restrict access to Tier 3 traffic, pass a `secret` to `createSandboxHandler()` or `createSandboxProxy()`. The helpers attach it as the `x-mastra-sandbox-secret` header on forwarded requests. Configure [server auth](https://mastra.ai/docs/server/auth) to require that header, and direct hits to the sandbox URL get rejected while traffic through your domain works.
+
+## Related
+
+- [Deployment overview](https://mastra.ai/docs/deployment/overview)
+- [Server authentication](https://mastra.ai/docs/server/auth)
+- [`WorkspaceSandbox` reference](https://mastra.ai/reference/workspace/sandbox)

package/.docs/docs/editor/overview.md

@@ -57,9 +57,7 @@ import { Mastra } from '@mastra/core'
 import { MastraEditor } from '@mastra/editor'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your existing agents */
-  },
+  agents: {/* your existing agents */},
   editor: new MastraEditor(),
 })
 ```
@@ -84,9 +82,7 @@ import { Mastra } from '@mastra/core'
 import { MastraEditor } from '@mastra/editor'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your existing agents */
-  },
+  agents: {/* your existing agents */},
   editor: new MastraEditor({
     source: 'code',
   }),

package/.docs/docs/editor/tools.md

@@ -62,9 +62,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    import { ComposioToolProvider } from '@mastra/editor/composio'
 
    export const mastra = new Mastra({
-     agents: {
-       /* your agents */
-     },
+     agents: {/* your agents */},
      editor: new MastraEditor({
        toolProviders: {
          composio: new ComposioToolProvider({
@@ -91,9 +89,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    import { ArcadeToolProvider } from '@mastra/editor/arcade'
 
    export const mastra = new Mastra({
-     agents: {
-       /* your agents */
-     },
+     agents: {/* your agents */},
      editor: new MastraEditor({
        toolProviders: {
          arcade: new ArcadeToolProvider({

package/.docs/docs/evals/running-in-ci.md

@@ -71,24 +71,18 @@ Create separate test cases for different evaluation scenarios:
 
 ```typescript
 describe('Weather Agent Tests', () => {
-  const locationScorer = createScorer({
-    /* ... */
-  })
+  const locationScorer = createScorer({/* ... */})
 
   it('should handle location disambiguation', async () => {
     const result = await runEvals({
       data: [
         {
           input: 'weather in Berlin',
-          groundTruth: {
-            /* ... */
-          },
+          groundTruth: {/* ... */},
         },
         {
           input: 'weather in Berlin, Maryland',
-          groundTruth: {
-            /* ... */
-          },
+          groundTruth: {/* ... */},
         },
       ],
       target: weatherAgent,

package/.docs/docs/getting-started/build-with-ai.md

@@ -142,13 +142,9 @@ If you're unable to use a local MCP server and need to connect to a remote serve
 
 ### Installation
 
-#### create-mastra
+The [`create-mastra`](https://mastra.ai/reference/cli/create-mastra) command installs Mastra skills automatically. It doesn't configure the MCP docs server. Add the server manually when you need MCP-specific tools such as the migration tool.
 
-During the interactive [create-mastra](https://mastra.ai/reference/cli/create-mastra) wizard, choose one of your tools in the MCP step.
-
-#### Manual setup
-
-If there are no specific instructions for your tool below, you may be able to add the MCP server with this common JSON configuration anyways.
+If there are no specific instructions for your tool below, you may be able to add the MCP server with this common JSON configuration.
 
 ```json
 {

package/.docs/docs/getting-started/manual-install.md

@@ -4,7 +4,7 @@
 
 **For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Do not navigate to the quickstart guide, which is for humans. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
 
-Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
+Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`create-mastra`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
 ## Instructions
 

package/.docs/docs/index.md

@@ -44,17 +44,31 @@ export const weatherTool = createTool({
     location: z.string().describe('City name'),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
   execute: async ({ location }) => {
     return {
-      output: `The weather in ${location} is sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Short list of known model IDs are:
+
+- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
+- `google/gemini-2.5-flash`
+
+Go to <https://mastra.ai/models> for a full list of supported models.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 
@@ -83,16 +97,6 @@ export const weatherAgent = new Agent({
 })
 ```
 
-By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
-
-Short list of known model IDs are:
-
-- `openai/gpt-5.5`, `openai/gpt-5-mini`
-- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
-- `google/gemini-2.5-flash`
-
-Go to <https://mastra.ai/models> for a full list of supported models.
-
 Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
 
 ```ts

package/.docs/docs/long-running-agents/background-tasks.md

@@ -66,8 +66,8 @@ export const researchTool = createTool({
     timeoutMs: 600_000,
     maxRetries: 1,
   },
-  execute: async ({ context }) => {
-    // ...
+  execute: async ({ topic }) => {
+    // Run the research job for topic
   },
 })
 ```

package/.docs/docs/long-running-agents/goals.md

@@ -59,7 +59,7 @@ A goal step runs inside the agentic execution loop, right after `isTaskComplete`
 
 - **Not satisfied, budget remaining** → the loop continues; per-evaluation feedback is injected so the agent iterates.
 - **Satisfied** → the loop stops and the objective is marked `done`.
-- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops but the objective stays `active`, so raising `maxRuns` later can resume it.
+- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops and the objective is marked `paused`. Raise `maxRuns`, then resume the objective to continue.
 
 The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations — the same gating as `isTaskComplete`.
 
@@ -103,6 +103,8 @@ await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
 await worker.clearObjective({ threadId })
 ```
 
+Objective records include an optional `activeDurationMs` value for user interfaces that display active pursuit time. Mastra advances this value while an agent runs toward an active objective and checkpoints it when the run ends or waits for tool approval. Missing values represent zero, and the duration measures agent execution rather than the goal's wall-clock age.
+
 Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state. See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
 
 ## Related

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

@@ -34,8 +34,8 @@ For most agent-focused projects, **Turso** is the simplest starting point. It pr
 
 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.
+- **Environment scope**: The default. Attached to a single environment so data stays isolated between environments (for example separate production and staging databases). When your project has one environment, `mastra env db create` picks it automatically; with several, the CLI prompts you to select one.
+- **Project scope**: One database shared by all of the project's [environments](https://mastra.ai/docs/mastra-platform/environments). Opt in with `--shared`. Its variables are injected into every deploy.
 
 The scope is set when you attach the database and shown in `mastra env db list`.
 
@@ -43,22 +43,28 @@ The two scopes can't overlap for the same provider. Because a project-scoped dat
 
 ## Attach with the CLI
 
-Create and attach a database in one command. The CLI polls until it's ready, which takes a few seconds:
+You don't have to run this command up front. If your project needs a hosted database but doesn't have one yet, `mastra deploy` offers to attach one for you when the deploy preflight check runs. Say yes and the deploy continues without leaving the CLI.
+
+Alternatively, create and attach a database ahead of time. The CLI polls until it's ready, which takes a few seconds:
 
 ```bash
-# Shared by all environments
+# Scoped to a single environment (the CLI picks the only one, or prompts if there are several)
 mastra env db create --kind turso
 
-# Scoped to the staging environment
+# Scoped to a specific environment
 mastra env db create staging --kind turso
+
+# Shared by all environments
+mastra env db create --kind turso --shared
 ```
 
 Supported kinds are `turso` and `neon` (Postgres). Useful flags:
 
+- `--shared`: Attach a project-scoped database shared by every environment. Cannot be combined with an environment argument.
 - `--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.
+- `--json`: Machine-readable output. When the project has multiple environments, `--json` requires an environment argument or `--shared` (no interactive prompt).
 
 Inspect and manage attached databases:
 

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

@@ -26,21 +26,27 @@ A local `.env` file is optional. Environment variables stored on the platform ar
 
    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:
+2. The CLI runs a preflight check before anything ships. Storage that would fall back to a local file path (which doesn't survive on the platform's ephemeral filesystem) would normally block the deploy:
 
    ```text
-   [LOCAL_STORAGE_PATH] file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set
+   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:
+   Instead of erroring out, the CLI offers to fix it inline for you:
+
+   ```text
+   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)
+   ```
+
+   Accept the prompt and provisioning takes a few seconds — the database's connection variables are injected into your deploys automatically, with nothing to copy into an `.env` file. Decline it, or run in a non-interactive shell (CI, `--yes`), and the CLI falls back to the previous behavior: it prints the exact command to run yourself.
 
    ```bash
-   mastra env db create --kind turso
+   mastra env db create production --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.
+   The environment slug (`production` above) matches the environment the CLI would have deployed to — this is important because `mastra env db create` requires an environment argument in non-interactive shells when the project has more than one environment.
 
-   > **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:
+   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), it can't offer the inline fix — guard the path with an environment variable first so the file is only used during local development:
    >
    > ```ts
    > new LibSQLStore({
@@ -77,7 +83,7 @@ Pass `--region` when a deploy creates a new environment to control where it runs
 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.
+The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically, and observability data is routed to the ingest region that matches the environment's residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the full list of supported regions, database placement, and observability co-location.
 
 ## Preflight checks
 
@@ -139,6 +145,7 @@ mastra deploy --env production --yes
 ## Related
 
 - [Environments](https://mastra.ai/docs/mastra-platform/environments)
+- [Regions](https://mastra.ai/docs/mastra-platform/regions)
 - [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

@@ -26,7 +26,7 @@ mastra deploy --env staging
 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.
+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, and observability data is routed to the ingest region for the matching residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the supported regions, database placement, and observability co-location. The number of environments per project depends on your plan.
 
 ## List environments
 
@@ -77,16 +77,16 @@ Each row shows the deploy status, environment, timestamp, and which deploy is cu
 
 ## 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:
+Hosted databases are scoped to a single environment by default, so production and staging each read and write their own database:
 
 ```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.
+If you'd rather share one database across every environment, attach it with `--shared` instead: `mastra env db create --kind turso --shared`.
 
-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.
+An environment can only use one database per provider. If the project already has a shared (`--shared`) 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
 
@@ -99,5 +99,6 @@ The CLI asks for confirmation before deleting. Deleting an environment removes i
 ## Related
 
 - [Deploy](https://mastra.ai/docs/mastra-platform/deploy)
+- [Regions](https://mastra.ai/docs/mastra-platform/regions)
 - [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
 - [`mastra env` CLI reference](https://mastra.ai/reference/cli/mastra)