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

package/.docs/docs/evals/multi-turn.md

@@ -0,0 +1,178 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Multi-turn evals
+
+Multi-turn evals test agent behavior across a conversation. Instead of a single `input`, you provide an `inputs` array. Each entry is sent sequentially to the agent on the same thread, and scorers see the accumulated output from all turns.
+
+## When to use multi-turn evals
+
+- The agent uses memory and must recall context from earlier turns
+- The agent handles follow-up questions that depend on prior responses
+- You need to verify tool-call sequences across a conversation
+- The agent runs a multi-step workflow (search, confirm, execute)
+
+## Quickstart
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: [
+        'What is the weather in Brooklyn?',
+        'What about tomorrow?',
+        'Compare the two forecasts.',
+      ],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [checks.calledTool('get_weather', { times: 2 }), checks.includes('Brooklyn')],
+})
+```
+
+Each turn runs `agent.generate()` with the same thread ID, so the agent sees the full conversation history. Scorers receive the accumulated output messages from all turns.
+
+## Memory is required for cross-turn recall
+
+Multi-turn recall depends on the agent having a **memory store configured**. The shared thread ID is what lets each turn see the earlier ones — but a thread only persists history when the agent has memory. If the agent has no memory configured, the turns still run sequentially and their outputs still accumulate for scoring, but the agent will not recall earlier turns (each input runs in isolation). `runEvals` logs a warning when you use `inputs` on an agent without memory.
+
+`runEvals` manages the conversation identity for you: it generates the shared `threadId` and injects a `resourceId` (Mastra memory scopes messages by resource + thread, so both are required for recall to work). By default the resource is derived from the generated thread so each conversation is isolated. To pin a specific resource — for example to reuse an existing user's memory — pass `targetOptions.memory.resource`; `runEvals` still owns the thread, so you don't provide one:
+
+```typescript
+await runEvals({
+  target: weatherAgent,
+  data: [{ inputs: ['What is the weather in Brooklyn?', 'What about tomorrow?'] }],
+  scorers: [checks.similarity('weather forecast')],
+  targetOptions: { memory: { resource: 'user-42' } },
+})
+```
+
+See [Memory](https://mastra.ai/docs/memory/overview) for how to configure a memory store.
+
+## How it works
+
+When a data item has an `inputs` array, `runEvals`:
+
+1. Creates a fresh thread (unique `threadId`) and resource for the conversation (a caller-provided `targetOptions.memory.resource` is preserved)
+2. Sends each input sequentially via `agent.generate()` on that thread
+3. Accumulates all output messages across turns
+4. Passes the full accumulated output to scorers for evaluation
+
+Scorers see the complete conversation output, not just the last turn.
+
+## Scoring semantics
+
+Two details matter when writing scorers for multi-turn items:
+
+- **`run.output` is the accumulated output from every turn.** Output-based scorers — `checks.includes`, `checks.calledTool`, `checks.similarity`, and similar — evaluate the whole conversation. For example, `checks.calledTool('get_weather', { times: 2 })` counts calls across all turns.
+- **`run.input` is only the first turn's input.** Scorers that compare input against output (faithfulness, answer relevancy, and other input-relative LLM scorers) only see the first user message, not the full conversation. Prefer output-based checks for multi-turn, or build scorers that read the accumulated `run.output` directly.
+
+## Per-turn assertions with `turns`
+
+The `inputs` form scores the **accumulated** output holistically — a single score over every turn's output. That can hide per-turn failures: an output-based check like `checks.includes('Brooklyn')` passes if _any_ turn mentions Brooklyn, even when the follow-up turn is broken.
+
+When you need to assert that a **specific turn** behaved correctly, use `turns` instead. Each turn is an object with its own `input` and optional `gates`/`scorers` that evaluate **only that turn's** input and output:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      turns: [
+        {
+          input: 'What is the weather in Brooklyn?',
+          gates: [checks.calledTool('get_weather')],
+        },
+        {
+          // The follow-up must call the tool again — it can't be satisfied
+          // by the first turn's tool call.
+          input: 'What about tomorrow?',
+          gates: [checks.calledTool('get_weather')],
+          scorers: [{ scorer: checks.similarity('tomorrow forecast'), threshold: 0.5 }],
+        },
+      ],
+    },
+  ],
+  target: weatherAgent,
+})
+
+result.verdict // 'passed' | 'scored' | 'failed'
+result.turnResults // per-turn gate/threshold/scorer outcomes
+```
+
+Semantics:
+
+- A per-turn gate or scorer sees **only that turn's** `run.input` and `run.output` — never the accumulated conversation. This fixes both blind spots of `inputs`: the wrong turn can't satisfy a check, and `run.input` is correct for each turn.
+- Per-turn outcomes fold into the overall [verdict](https://mastra.ai/docs/evals/gates-and-verdicts): a failing turn gate makes the verdict `failed`; a missed turn threshold (with gates passing) makes it `scored`.
+- `result.turnResults[i]` reports each turn's `gateResults`, `thresholdResults`, and `scores`, so a failure points at the exact turn. Across multiple conversations, turn results are averaged by turn index.
+- A turn with no `gates`/`scorers` just advances the conversation.
+- Top-level `scorers`/`gates` still run holistically over the accumulated output, so you can combine "this turn must call the tool" with "the overall answer mentions Brooklyn."
+- When the agent has storage configured, each per-turn scorer/gate result is persisted like top-level scores, so per-turn outcomes appear in your scores store. Each stored per-turn score is labeled with its turn index (`metadata.turnIndex`), shares the conversation's `threadId`, and links to that turn's own trace span.
+
+Use `inputs` when a single holistic score over the whole conversation is enough; use `turns` when correctness depends on individual turns. `turns` cannot be combined with `input` or `inputs` in the same data item.
+
+## Combining with gates and thresholds
+
+Multi-turn data items work with [gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts). Use output-based scorers so gating reflects the full conversation:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
+    },
+  ],
+  target: weatherAgent,
+  gates: [checks.calledTool('get_weather')],
+  scorers: [{ scorer: checks.similarity('Brooklyn weather forecast'), threshold: 0.5 }],
+})
+
+result.verdict // 'passed' | 'scored' | 'failed'
+```
+
+## Mixing single-turn and multi-turn
+
+A single `runEvals` call can include both single-turn and multi-turn data items:
+
+```typescript
+const result = await runEvals({
+  data: [
+    { input: 'What is the weather in Brooklyn?' },
+    {
+      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [checks.includes('Brooklyn')],
+})
+```
+
+Single-turn items use `input` as usual. Multi-turn items use `inputs` — `input` can be omitted entirely.
+
+## Validation
+
+`runEvals` throws a `MastraError` if `inputs` is present but empty:
+
+```typescript
+// Throws: 'inputs' must be a non-empty array
+await runEvals({
+  data: [{ inputs: [] }],
+  target: myAgent,
+  scorers: [myScorer],
+})
+```
+
+## Related
+
+- [`runEvals()` reference](https://mastra.ai/reference/evals/run-evals): Full API for `runEvals` parameters and returns
+- [Gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Enforce hard requirements and quality thresholds
+- [Quick Checks](https://mastra.ai/docs/evals/quick-checks): Zero-LLM composable micro-scorers

package/.docs/docs/evals/overview.md

@@ -142,6 +142,7 @@ Once registered, you can score traces interactively within Studio under the **Ob
 
 - Use [Quick Checks](https://mastra.ai/docs/evals/quick-checks) for fast, deterministic assertions on text and tool usage
 - Add [gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts) to enforce hard requirements and quality thresholds
+- Test [multi-turn conversations](https://mastra.ai/docs/evals/multi-turn) where behavior emerges across sequential turns
 - Learn how to create your own scorers in the [Creating Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide
 - Explore built-in scorers in the [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers) section
 - Test scorers with [Studio](https://mastra.ai/docs/studio/overview)

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/file-based-agents.md

@@ -10,9 +10,9 @@ File-based agents are an experimental, convention-based way to define [Mastra ag
 
 This approach reduces glue code and makes the file system itself a direct representation of your [project structure](https://mastra.ai/reference/project-structure), so both you and your coding agent can understand it at a glance.
 
-You can build your entire project with file-based agents or combine this approach with agents and other primitives defined directly in code, making it easy to adopt incrementally.
+You can build your entire project with file-based agents or combine this approach with agents and other primitives defined directly in code for incremental adoption.
 
-File-based agents have some limitations while in beta. Not every Mastra feature can be defined in a file yet, and they are not the best fit for dynamic configuration or runtime wiring. When needed, you can define agents and related primitives directly in code.
+File-based agents have some limitations while in beta. Not every Mastra feature can be defined in a file yet, and they're not the best fit for dynamic configuration or runtime wiring. When needed, you can define agents and related primitives directly in code.
 
 > **Note:** All Mastra documentation currently shows agents and primitives defined directly in code. File-based agents use the same underlying concepts and APIs, so the guidance elsewhere in the docs still applies. As file-based agents mature, more examples may use this structure where appropriate.
 

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/durable-agents.md

@@ -159,8 +159,9 @@ cleanup()
 ```typescript
 import { createDurableAgent } from '@mastra/core/agent/durable'
 import { RedisServerCache } from '@mastra/redis'
+import Redis from 'ioredis'
 
-const cache = new RedisServerCache({ url: 'redis://localhost:6379' })
+const cache = new RedisServerCache({ client: new Redis('redis://localhost:6379') })
 
 export const durableAgent = createDurableAgent({
   agent,

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

@@ -30,7 +30,7 @@ const pinger = new Agent({
 
 const mastra = new Mastra({
   agents: { pinger },
-  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
 })
 
 await mastra.schedules.create({
@@ -164,7 +164,7 @@ Hooks let you run code at key points in an agent schedule's lifecycle, for examp
 ```typescript
 const mastra = new Mastra({
   agents: { pinger },
-  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
   schedules: {
     prepare: async ({ agentId, schedule, trigger }) => {
       // Return overrides, null to skip this fire, or undefined for defaults

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:
 
@@ -99,6 +105,7 @@ Turso exposes two environment variables: `TURSO_DATABASE_URL` and `TURSO_AUTH_TO
 import { LibSQLStore } from '@mastra/libsql'
 
 export const storage = new LibSQLStore({
+  id: 'mastra-storage',
   url: process.env.TURSO_DATABASE_URL!,
   authToken: process.env.TURSO_AUTH_TOKEN!,
 })

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

@@ -26,24 +26,31 @@ 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({
+   >   id: 'mastra-storage',
    >   // 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,
@@ -76,18 +83,19 @@ 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
 
 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:
+- **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's set locally, stored on the platform, or provided by a managed database:
 
   ```ts
   import { LibSQLStore } from '@mastra/libsql'
 
   export const storage = new LibSQLStore({
+    id: 'mastra-storage',
     // 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,
@@ -137,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)

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

@@ -10,7 +10,7 @@ The [Mastra platform](https://projects.mastra.ai) provides three products for de
 
 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.
 
-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.
+Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`), provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data, and get a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspace) per environment that gives agents a filesystem and a sandbox with no manual configuration.
 
 ## Get started
 

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

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Regions
+
+A region controls where a platform environment runs, where its [hosted database](https://mastra.ai/docs/mastra-platform/database) is placed, and where its observability data is stored. The region is fixed when the environment is created and can't be changed later.
+
+Mastra platform offers two residency zones today, `us` and `eu`, backed by specific compute regions on Railway. Databases and observability follow the environment's region automatically.
+
+## Choose a region
+
+Pass `--region` when creating or first deploying to an environment:
+
+```bash
+mastra deploy --env production --region eu
+mastra env create staging --region us
+```
+
+Both `mastra deploy --region` and `mastra env create --region` accept either the `us` / `eu` shorthand or a canonical Railway region code from the table below. Shorthand is the recommended form.
+
+The default when no region is passed is `us`, which resolves to `pdx` (Portland, Oregon).
+
+## Available regions
+
+The residency selector offers four Railway regions across two zones. `us` and `eu` shorthand resolve to the underlined default in each zone.
+
+| Zone | Railway code    | Location                  |
+| ---- | --------------- | ------------------------- |
+| `us` | `pdx` (default) | Portland, Oregon          |
+| `us` | `iad`           | Ashburn, Virginia         |
+| `us` | `sfo`           | San Francisco, California |
+| `eu` | `ams` (default) | Amsterdam, Netherlands    |
+
+Pass a Railway code directly when you need to pin an environment to a specific data center. Passing `us` selects `pdx`, and passing `eu` selects `ams`.
+
+> **Note:** Additional Railway regions exist in the deploy pipeline (for example Singapore, `sin`) but aren't offered in the residency selector yet, because hosted databases and observability don't have local placement outside the US and EU. Passing an unrecognized region falls back to the US default rather than pinning to it.
+
+## Hosted database placement
+
+When you attach an [environment-scoped database](https://mastra.ai/docs/mastra-platform/database), the platform picks the provider region closest to the environment. This is server-authoritative, so an explicit `--region` on `mastra env db create <env>` is ignored. The environment's region is the source of truth.
+
+| Environment region | Turso region      | Postgres (Neon) region         |
+| ------------------ | ----------------- | ------------------------------ |
+| `pdx`              | `sjc` (San Jose)  | `aws-us-west-2` (Oregon)       |
+| `iad`              | `iad` (Ashburn)   | `aws-us-east-1` (N. Virginia)  |
+| `sfo`              | `sjc` (San Jose)  | `aws-us-west-2` (Oregon)       |
+| `ams`              | `ams` (Amsterdam) | `aws-eu-central-1` (Frankfurt) |
+
+Project-scoped databases (shared across environments) accept an explicit `--region` because they aren't bound to a single environment. Use a provider region ID for the flag, not the `us` / `eu` shorthand:
+
+```bash
+mastra env db create --kind turso --region fra
+mastra env db create --kind neon --region aws-us-east-1
+```
+
+Turso offers 20+ regions and Postgres (Neon) is available across AWS and Azure regions in the US, EU, and APAC. See the [Turso regions list](https://docs.turso.tech/features/data-edge#locations) and [Neon regions list](https://neon.com/docs/introduction/regions) for the full set. Passing a code not offered by the provider fails at attach time with the provider's error.
+
+## Observability co-location
+
+Observability ingest runs in two regions today: **US** (Iowa, `us-central1`) and **EU** (Amsterdam). Every environment's traces, logs, and metrics are routed to the ingest region that matches its residency zone:
+
+| Environment region                  | Observability region |
+| ----------------------------------- | -------------------- |
+| `pdx`, `iad`, `sfo`, `us` shorthand | US (Iowa)            |
+| `ams`, `eu` shorthand               | EU (Amsterdam)       |
+
+Compute and databases can be placed in more Railway and provider regions than observability supports, so co-location isn't perfect for every combination. A `us`-zone environment always sends telemetry to US ingest, and an `eu`-zone environment always sends telemetry to EU ingest, even if the underlying Railway region is a specific city not directly served by an ingest endpoint. Data residency is preserved at the zone level. Telemetry from an `eu` environment never crosses into the US.
+
+## Related
+
+- [Deploy](https://mastra.ai/docs/mastra-platform/deploy)
+- [Environments](https://mastra.ai/docs/mastra-platform/environments)
+- [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
+- [Observability](https://mastra.ai/docs/mastra-platform/observability)