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

package/.docs/docs/getting-started/file-based-agents.md

@@ -6,13 +6,15 @@
 
 > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-File-based agents are a new, convention-based way to define Mastra agents and project primitives from a directory structure under `src/mastra/`. You'll like this approach if you want an agent to be self-contained, easy to scan and extend.
+File-based agents are an experimental, convention-based way to define [Mastra agents](https://mastra.ai/docs/agents/overview) and the primitives they use in files under `src/mastra/`, instead of registering them manually on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
 
-Adopting this feature is a fundamental decision about how to structure your project. You'll need to follow the file conventions and be aware of its limitations, namely that you can't use dynamic configuration or runtime wiring.
+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.
 
-However, you can use file-based agents, code-defined agents, or both in the same project. All Mastra docs currently use code-first examples. As file-based agents mature, more examples may use this structure where it makes sense.
+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.
 
-Under the hood Mastra is assembling code-defined agents and primitives from the files you create. So explanations and concepts you can find on other docs pages apply to file-based agents as well.
+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.
+
+> **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.
 
 ## Basic layout
 
@@ -70,12 +72,15 @@ Map each primitive or feature to its file convention:
 | [Memory](https://mastra.ai/reference/file-based-agents/memory)                   | `src/mastra/agents/<agent-id>/memory.ts`                                                  |
 | [Workspace](https://mastra.ai/reference/file-based-agents/workspace)             | `src/mastra/agents/<agent-id>/workspace.ts` and `src/mastra/agents/<agent-id>/workspace/` |
 | [Processors](https://mastra.ai/reference/file-based-agents/processors)           | `src/mastra/agents/<agent-id>/processors/`                                                |
+| [Scorers](https://mastra.ai/reference/file-based-agents/scorers)                 | `src/mastra/agents/<agent-id>/scorers/`                                                   |
 | [Subagents](https://mastra.ai/reference/file-based-agents/subagents)             | `src/mastra/agents/<agent-id>/subagents/`                                                 |
 | [Workflows](https://mastra.ai/reference/file-based-agents/workflows)             | `src/mastra/workflows/`                                                                   |
 | [Storage](https://mastra.ai/reference/file-based-agents/storage)                 | `src/mastra/storage.ts`                                                                   |
 | [Observability](https://mastra.ai/reference/file-based-agents/observability)     | `src/mastra/observability.ts`                                                             |
+| [Logger](https://mastra.ai/reference/file-based-agents/logger)                   | `src/mastra/logger.ts`                                                                    |
 | [Server config](https://mastra.ai/reference/file-based-agents/server)            | `src/mastra/server.ts`                                                                    |
 | [Studio config](https://mastra.ai/reference/file-based-agents/studio)            | `src/mastra/studio.ts`                                                                    |
+| [Schedules](https://mastra.ai/docs/long-running-agents/schedules)                | Not yet file-based — create at runtime with `mastra.schedules.create()`                   |
 
 ## Discovery lifecycle
 

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

@@ -168,7 +168,7 @@ const stream = await agent.stream('Research solana for me', {
 })
 ```
 
-> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
+Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
 
 ### Aggregate properties
 

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

@@ -60,9 +60,7 @@ for await (const chunk of output.fullStream) {
 cleanup()
 ```
 
-The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client.
-
-> **Note:** Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
+The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client. Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
 
 ## How it works
 
@@ -140,7 +138,7 @@ const agent = new Agent({
 export const inngestAnalyst = createInngestAgent({ agent, inngest })
 ```
 
-> **Note:** Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
+Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
 
 ## Resumable streams
 
@@ -199,7 +197,7 @@ await durableAgent.stream('Research topic', {
 })
 ```
 
-> **Note:** Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
+Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
 
 ## Cleanup
 

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

@@ -103,9 +103,7 @@ await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
 await worker.clearObjective({ threadId })
 ```
 
-Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state.
-
-> **Note:** See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
+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/long-running-agents/signal-providers.md

@@ -157,9 +157,7 @@ export class CiSignals extends SignalProvider<'ci-signals'> {
 }
 ```
 
-`handleWebhook()` is a provider method, not an auto-mounted HTTP route. Invoke it from your own endpoint, passing the request body, headers, and any route params.
-
-> **Note:** Visit [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider) for subscription, polling, lifecycle, and `notify()` details. For the complete notification payload shape, including deduplication and coalescing fields, visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent).
+`handleWebhook()` is a provider method, not an auto-mounted HTTP route. Invoke it from your own endpoint, passing the request body, headers, and any route params. Visit [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider) for subscription, polling, lifecycle, and `notify()` details. For the complete notification payload shape, including deduplication and coalescing fields, visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent).
 
 ## Built-in webhook provider
 

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

@@ -112,9 +112,7 @@ const result = agent.sendSignal(
 await result.persisted
 ```
 
-Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context.
-
-> **Note:** Visit [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for `ifActive`, `ifIdle`, branch attributes, and `streamOptions`.
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. Visit [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for `ifActive`, `ifIdle`, branch attributes, and `streamOptions`.
 
 ### Send notification context
 
@@ -199,9 +197,7 @@ Awaiting `sendSignal()` preserves stream echo ordering when a subscribed thread
 
 ### Conditional attributes
 
-Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Top-level `attributes` always apply, and Mastra merges the selected branch's `attributes` into them when the input is accepted.
-
-> **Note:** Visit [`Agent.sendMessage()` reference](https://mastra.ai/reference/agents/agent) and [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for branch-specific attributes.
+Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Top-level `attributes` always apply, and Mastra merges the selected branch's `attributes` into them when the input is accepted. Visit [`Agent.sendMessage()` reference](https://mastra.ai/reference/agents/agent) and [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for branch-specific attributes.
 
 ## State and notification signals
 
@@ -276,9 +272,7 @@ Notification signals represent external events such as GitHub activity, email, S
 
 Notification delivery has two phases. During ingress, `agent.sendNotificationSignal()` stores a notification record and resolves the agent's delivery policy. During dispatch, Mastra consumes due records and emits full notification or summary signals.
 
-The default delivery policy is priority-aware. Urgent notifications deliver immediately, while lower-priority notifications may be batched into summaries or wait until the thread is idle.
-
-> **Note:** Visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent) for notification fields, [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` configuration, and [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for inbox tool actions.
+The default delivery policy is priority-aware. Urgent notifications deliver immediately, while lower-priority notifications may be batched into summaries or wait until the thread is idle. Visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent) for notification fields, [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` configuration, and [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for inbox tool actions.
 
 ```typescript
 await agent.sendNotificationSignal(
@@ -314,15 +308,11 @@ Notification summaries tell the model that inbox records are waiting:
 
 When Mastra emits a summary, it clears `summaryAt` and sets `summarySignalId` on each summarized record. The records stay pending and readable. When Mastra emits a full notification, it sets `deliveredSignalId` and marks the record `delivered`. If the inbox tool reads a notification first, it can inject the full notification signal and mark the record `seen`, which prevents duplicate full delivery.
 
-Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup. Enable scheduled dispatch at the Mastra level when deferred notifications and summary rollups should be delivered automatically.
-
-> **Note:** Visit [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` and [`Mastra` class reference](https://mastra.ai/reference/core/mastra-class) for runtime notification dispatch configuration.
+Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup. Enable scheduled dispatch at the Mastra level when deferred notifications and summary rollups should be delivered automatically. Visit [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` and [`Mastra` class reference](https://mastra.ai/reference/core/mastra-class) for runtime notification dispatch configuration.
 
 #### Notification inbox tool
 
-Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The notification contents are delivered as signals, not as normal tool output.
-
-> **Note:** Visit [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for the setup example, input schema, and action behavior.
+Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The notification contents are delivered as signals, not as normal tool output. Visit [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for the setup example, input schema, and action behavior.
 
 `sendNotificationSignal()` requires a storage domain with `notifications` support. Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
@@ -358,15 +348,11 @@ Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `
 - `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
 - `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
 
-Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server.
-
-> **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
+Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server. Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
 ### Approve tool calls
 
-When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The resumed chunks arrive through the existing thread subscription.
-
-> **Note:** Visit [`client.getAgent().sendToolApproval()` reference](https://mastra.ai/reference/client-js/agents) and [server agent routes](https://mastra.ai/reference/server/routes) for request and response shapes.
+When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The resumed chunks arrive through the existing thread subscription. Visit [`client.getAgent().sendToolApproval()` reference](https://mastra.ai/reference/client-js/agents) and [server agent routes](https://mastra.ai/reference/server/routes) for request and response shapes.
 
 ### Use HTTP routes
 

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/github.md

@@ -9,7 +9,7 @@ The GitHub integration links a Mastra platform project to a GitHub repository. W
 After a repository is linked, the platform:
 
 - Builds and deploys Studio and Server on every push to the configured branches.
-- Provisions managed databases and the Mastra gateway API key for projects created from a template.
+- Provisions managed databases and the Gateway API key for projects created from a template.
 - Surfaces commit, branch, and pull request context on each deploy.
 - Reports build status back to GitHub as check runs and to the project dashboard with live status badges and inline logs.
 
@@ -59,7 +59,7 @@ Templates are the fastest way to get started. The platform creates a new reposit
 
 3. Configure the template's managed database requirements. Templates can declare required databases (such as Turso or Neon) and you pick the provider and region per requirement.
 
-4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Mastra gateway works on the first deploy.
+4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Gateway works on the first deploy.
 
 5. Select **Create project**. The platform creates the repository, writes a `.mastra-project.json` config file into it, provisions the managed databases, and triggers the initial Studio and Server deploys.