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

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

@@ -4,15 +4,15 @@
 
 Observability on Mastra platform is a standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys. Use it when you want observability without deploying Studio first or setting up local storage.
 
-Mastra can configure platform observability during project setup. The CLI provisions a platform project, writes the required environment variables, and registers observability exporters in your Mastra config.
+Use `mastra init` to configure platform observability while adding Mastra to an existing application, or configure it manually in a newly created Mastra project.
 
 ## Quickstart
 
-Choose the setup path that matches your project. New and existing projects can use the CLI to provision Observability automatically, while manual setup is available when you already manage platform projects and environment variables yourself.
+Choose the setup path that matches your project.
 
 ### New project
 
-Create a new Mastra project:
+Create a managed Mastra project. When prompted, opt into Mastra Platform Observability to configure it automatically:
 
 **npm**:
 
@@ -38,15 +38,7 @@ yarn create mastra
 bunx create-mastra
 ```
 
-When prompted, enable Mastra Observability:
-
-```bash
-Enable Mastra Observability? (will open auth flow)
-
-> Yes
-```
-
-The CLI authenticates with Mastra platform, creates a platform project, writes the required environment variables, and configures the observability exporters.
+When you select observability, the create command authenticates with Mastra Platform, provisions a platform project, and writes the credentials to your project. If you skip platform setup or use a prompt-free creation flow, follow the [manual setup](#manual-setup) steps instead.
 
 ### Existing non-Mastra projects
 

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)

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

@@ -0,0 +1,111 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspace
+
+A workspace gives an environment two things your agents can use at runtime:
+
+- A **bucket** for filesystem storage, exposed to your code as [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem).
+- A **sandbox** for executing commands, exposed as [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox).
+
+Workspaces are provisioned per [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` each get their own bucket and sandbox. The platform manages provisioning, credentials, and lifecycle; your deploy code only needs to construct the providers.
+
+## When workspaces are provisioned
+
+New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
+
+Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
+
+If provisioning fails for an environment — for example while Railway is under load — the Workspaces tab shows the failure and offers a retry. The environment itself is still created; only the workspace is unavailable until you retry.
+
+## Use the workspace from your code
+
+Install the provider package:
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Compose the providers into a workspace and register it with Mastra:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
+
+export const workspace = new Workspace({
+  filesystem: new PlatformFilesystem(),
+  sandbox: new PlatformSandbox(),
+})
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workspace } from './workspace'
+
+export const mastra = new Mastra({
+  workspace,
+})
+```
+
+`PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
+
+## Injected environment variables
+
+Every deploy that runs on a platform environment with a workspace receives these variables:
+
+| Variable                      | Contents                                                                                                                                                 |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_SECRET_KEY`  | Secret key scoped to the deploy. Used by the workspace providers to authenticate. `MASTRA_PLATFORM_ACCESS_TOKEN` is also injected as a deprecated alias. |
+| `MASTRA_PROJECT_ID`           | Project the deploy belongs to.                                                                                                                           |
+| `MASTRA_ENVIRONMENT_ID`       | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                         |
+| `MASTRA_PLATFORM_BUCKET_NAME` | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                                     |
+
+These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
+
+## Local development
+
+Reuse the same providers locally by putting the four variables in your `.env` file. Get the values from your project's Workspaces tab:
+
+```bash
+MASTRA_PLATFORM_SECRET_KEY=your-secret-key
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_ENVIRONMENT_ID=your-environment-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform — they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
+
+For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
+
+## Inspect the workspace
+
+The Workspaces tab in your platform project shows, per environment:
+
+- Bucket status and its contents, with upload, download, and delete actions.
+- Recent sandbox sessions with their command, exit code, and duration.
+- Provisioning failures with a **Retry** action.
+
+## See also
+
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem) — reference for the filesystem provider.
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox) — reference for the sandbox provider.
+- [Environments](https://mastra.ai/docs/mastra-platform/environments) — how environments scope workspaces, variables, and databases.

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

@@ -8,7 +8,7 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
 
 ## Quickstart
 
-Enable `observationalMemory` in the memory options when creating your agent:
+Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -27,7 +27,54 @@ export const agent = new Agent({
 })
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. Config objects also use this model unless you set a different one. To use a different model, pass it in the config object:
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
+The following script creates a local LibSQL database, enables Observational Memory, and uses one resource and thread across two agent calls:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'memory-storage',
+    url: 'file:./memory.db',
+  }),
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+    },
+  },
+})
+
+const agent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory,
+})
+
+const memoryOptions = {
+  resource: 'user-123',
+  thread: 'conversation-123',
+}
+
+const firstResponse = await agent.generate('Remember that my favorite color is blue.', {
+  memory: memoryOptions,
+})
+console.log(firstResponse.text)
+
+const secondResponse = await agent.generate('What is my favorite color?', {
+  memory: memoryOptions,
+})
+console.log(secondResponse.text)
+```
+
+The `resource` identifies the user or entity, while the `thread` identifies the conversation. Reuse both values to continue the same conversation. Observational Memory processes the stored history as it grows and replaces older messages with observations when its activation conditions are met.
+
+The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model, pass it in the config object:
 
 ```typescript
 const memory = new Memory({
@@ -237,6 +284,34 @@ new Extractor({
 })
 ```
 
+#### Read extracted values from a stream
+
+Extractor results are emitted when OM completes an observation or reflection. Read both completion data parts from the stream:
+
+```typescript
+const stream = await agent.stream('Remember that I prefer dark mode.')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-om-observation-end' || chunk.type === 'data-om-buffering-end') {
+    const { operationType, extractedValues = {}, extractionFailures = [] } = chunk.data
+
+    for (const [slug, value] of Object.entries(extractedValues)) {
+      console.log(`${operationType} extractor ${slug}:`, value)
+    }
+
+    for (const failure of extractionFailures) {
+      console.error(`Extractor ${failure.slug} failed:`, failure.error)
+    }
+  }
+}
+```
+
+`extractedValues` uses each extractor's slug as its key. Both result fields are optional, and a failed extractor doesn't remove values from successful extractors.
+
+`data-om-observation-end` reports a synchronous completion. `data-om-buffering-end` reports completed background work. Its extractor metadata is persisted immediately, but the buffered content remains inactive until activation. Check `operationType` to determine whether the completed work was an observation or reflection.
+
+See the [`data-om-observation-end`](https://mastra.ai/reference/memory/observational-memory) and [`data-om-buffering-end`](https://mastra.ai/reference/memory/observational-memory) reference tables for the complete payloads.
+
 ### Working memory updates
 
 Use `observationalMemory.observation.manageWorkingMemory` to let the Observer manage working memory automatically. The main agent no longer needs to call the working memory tool while it handles the user request, so working memory updates don't depend on the agent remembering to make them.

package/.docs/docs/memory/overview.md

@@ -81,6 +81,8 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
+   **For AI agents:** Important: Add `id` to `LibSQLStore`.
+
    ```typescript
    import { Mastra } from '@mastra/core'
    import { LibSQLStore } from '@mastra/libsql'
@@ -151,6 +153,8 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
 
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'

package/.docs/docs/observability/feedback.md

@@ -127,6 +127,10 @@ const ratingsOverTime = await observability!.getFeedbackTimeSeries({
 
 See the [feedback reference](https://mastra.ai/reference/observability/feedback) for all fields, filters, return types, and percentile query parameters.
 
+## Export feedback to external platforms
+
+Feedback flows through the observability event bus, so exporters that support feedback forward it automatically. The [PostHog exporter](https://mastra.ai/reference/observability/tracing/exporters/posthog) sends feedback as native `$ai_feedback` events that appear on the linked trace in PostHog.
+
 ## Related
 
 - [Observability overview](https://mastra.ai/docs/observability/overview)

package/.docs/docs/observability/integrations/bridges/otel.md

@@ -126,9 +126,7 @@ export const mastra = new Mastra({
       },
     },
   }),
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
 })
 ```
 

package/.docs/docs/observability/integrations/exporters/otel.md

@@ -425,9 +425,7 @@ To disable a signal, set the `signals` option:
 
 ```typescript
 new OtelExporter({
-  provider: {
-    /* ... */
-  },
+  provider: {/* ... */},
   signals: {
     traces: true, // default
     logs: false, // disable log export

package/.docs/docs/server/auth/fga.md

@@ -254,6 +254,46 @@ class MyFGAProvider implements IFGAProvider {
 }
 ```
 
+## System actors
+
+Autonomous and scheduled agents run without an end user. Mark these calls with an actor signal so FGA can tell them apart from user requests:
+
+- `true` or `{ actorKind: 'system' }` identifies an anonymous system actor.
+- The object form can also carry `agentId`, `permissions`, and `scope` to identify and constrain the acting agent.
+
+By default, a trusted actor skips the user-centric `require()` check after a tenant-scope check. To enforce per-agent least privilege, implement the optional `requireActor` method on your provider. It receives the actor and the same `FGACheckParams` as `require`, and throws `FGADeniedError` to deny. When your provider doesn't implement `requireActor`, the trusted-actor bypass is preserved, so adding it is backward compatible.
+
+```typescript
+import { FGADeniedError } from '@mastra/core/auth/ee'
+import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'
+
+class MyFGAProvider implements IFGAProvider {
+  // ...check, require, filterAccessible...
+
+  async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
+    const agentId = actor === true ? undefined : actor.agentId
+    // Resolve the agent's real grants from a trusted source keyed by agentId.
+    const granted = await this.grantsForAgent(agentId)
+    const required = Array.isArray(params.permission) ? params.permission : [params.permission]
+    if (!required.some(permission => granted.includes(permission))) {
+      throw new FGADeniedError(null, params.resource, params.permission)
+    }
+  }
+}
+```
+
+### Trust requirements
+
+The actor signal is trusted input, so construct it server-side:
+
+- Treat `actor` as a per-call signal. Durable workflows forward it when a run starts, but don't restore the initial actor on resume. Pass it explicitly on every trusted resume, or resolve a fresh actor through agent `defaultOptions`. Without a current actor, user authorization applies and a missing user fails closed.
+- Mastra strips `actor` from execution options handled by its built-in agent HTTP routes. Set it in server-side code, for example a scheduled job or a workflow, never from client input.
+- Establish tenant scope server-side. Built-in agent HTTP routes ignore a client-supplied `organizationId` in the request context, and the trusted-actor path requires an `organizationId` to be set.
+- Durable resume keeps its existing request-context recovery and merge behavior. This doesn't make a persisted actor trusted for a later workflow segment.
+- The tenant-scope check confirms that a trusted `organizationId` exists. It doesn't verify that `actor.agentId` belongs to that organization. When that relationship matters, verify it in `requireActor` using authoritative provider data.
+- Treat `actor.permissions` as a claim, not a grant. A provider that enforces least privilege resolves the agent's authoritative permissions from a trusted source, for example a manifest or your FGA backend keyed by `agentId`, rather than trusting the inline values.
+- Once a provider implements `requireActor`, errors from that method stop execution. Mastra doesn't fall back to organization-only authorization.
+
 ## Related
 
 - [Authentication overview](https://mastra.ai/docs/server/auth)

package/.docs/docs/server/auth/simple-auth.md

@@ -74,9 +74,7 @@ Add custom headers using the `headers` option:
 
 ```typescript
 new SimpleAuth({
-  tokens: {
-    /* ... */
-  },
+  tokens: {/* ... */},
   headers: ['X-API-Key', 'X-Custom-Auth'],
 })
 ```

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

@@ -91,6 +91,8 @@ See [request context](https://mastra.ai/docs/server/request-context) for configu
 
 ## Evaluation
 
+Use the date filter to limit score metrics to a preset or custom time range.
+
 ### Scorers
 
 The Scorers tab displays the results of your agent's scorers as they run. When messages pass through your agent, the defined scorers evaluate each output asynchronously and render their results here. This allows you to understand how your scorers respond to different interactions, compare performance across test cases, and identify areas for improvement.

package/.docs/docs/workflows/control-flow.md

@@ -591,9 +591,7 @@ const embedStep = createStep({
   inputSchema: z.object({ chunk: z.string() }),
   outputSchema: z.object({ embedding: z.array(z.number()) }),
   execute: async ({ inputData }) => ({
-    embedding: [
-      /* vector embedding */
-    ],
+    embedding: [/* vector embedding */],
   }),
 })
 

package/.docs/docs/workspace/filesystem.md

@@ -23,6 +23,7 @@ Available providers:
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
 - [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
 - [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem): Stores files in Google Cloud Storage
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): Stores files in a Mastra Platform workspace bucket
 - [`GoogleDriveFilesystem`](https://mastra.ai/reference/workspace/google-drive-filesystem): Stores files inside a Google Drive folder
 - [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem): Stores files in Azure Blob Storage
 - [`FilesSDKFilesystem`](https://mastra.ai/reference/workspace/files-sdk-filesystem): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more) — useful when you want one provider that can target multiple backends

package/.docs/docs/workspace/sandbox.md

@@ -26,6 +26,7 @@ A sandbox provider executes commands in a controlled environment:
 - [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
 - [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
 - [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): Executes commands in a sandbox tied to a Mastra Platform environment
 - [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox): Executes commands in ephemeral, isolated Railway cloud sandboxes
 
 ## Basic usage

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

@@ -2,21 +2,21 @@
 
 # Mastra Quickstart
 
-**For AI agents:** This page provides information for humans on how to run an interactive CLI to create a boilerplate Mastra project (with agents, workflows, and tools). You can run it non-interactively like so: `npm create mastra@latest <project-name> -- --default`. If you need to build a Mastra project from scratch (e.g. as a Node.js script printing to stdout), navigate to <https://mastra.ai/docs/getting-started/manual-install> instead.
+**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install).
 
-The `create mastra` CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt.
+The `create-mastra` CLI is the quickest way to start a Mastra project. It creates an agent harness with workspace tools, memory, task tracking, web access, schedules, storage, and observability.
 
-If you need more control over the setup, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). You can also use [`mastra init`](https://mastra.ai/reference/cli/mastra) for existing projects.
+For more control, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
-> **📹 Watch:** Watch [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
+> **📹 Watch:** Watch the [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
 
 ## Before you begin
 
-- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
+You'll need an API key from OpenAI, Anthropic, Google Gemini, or xAI. You can skip entering it during setup and add it to `.env` later.
 
-## Initialize Mastra
+## Create the project
 
-You can run `create mastra` anywhere on your machine. Start the setup wizard:
+Run the interactive setup:
 
 **npm**:
 
@@ -42,32 +42,47 @@ yarn create mastra
 bunx create-mastra
 ```
 
-You'll be prompted for various configuration options, including your LLM provider and whether to enable [Observability](https://mastra.ai/docs/mastra-platform/observability) on the Mastra platform.
+The command asks for a project name, model provider, and optional API key. It then installs dependencies, installs Mastra skills for your coding assistants, and creates an initial Git commit when you aren't already inside a repository.
 
-The wizard creates a new directory for your project with a `src/mastra` folder containing an example weather agent and the following files:
+The generated `src/mastra` directory contains the Mastra entry point, agent, workspace tools, and supporting code. See the [project structure reference](https://mastra.ai/reference/project-structure) for the standard Mastra layout.
 
-- `index.ts`: Entry point for all Mastra-related code and configuration
-- `agents/weather-agent.ts`: A weather agent with a prompt that uses the tool
-- `tools/weather-tool.ts`: A tool to fetch weather for a given location
-- `workflows/weather-workflow.ts`: A workflow that runs the weather agent
-- `scorers/weather-scorer.ts`: A scorer to evaluate the weather agent's responses
+> **Tip:** Use `--template <template>` to start from a template, or `--empty` to create a minimal provider-free project. Use `--no-skills` or `--no-git` to skip automatic setup. See the [`create-mastra` reference](https://mastra.ai/reference/cli/create-mastra) for all flags.
 
-Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/getting-started/build-with-ai) or the [MCP Docs Server](https://mastra.ai/docs/getting-started/build-with-ai) installed. Learn more about Mastra's [project structure](https://mastra.ai/reference/project-structure).
+## Test your agent
 
-> **Tip:** You can use [flags](https://mastra.ai/reference/cli/create-mastra) with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates).
+Follow the terminal instructions to enter the project directory and start the development server:
 
-## Test your agent
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
 
-Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open Studio at [localhost:4111](http://localhost:4111).
+```bash
+bun run dev
+```
 
-Try asking about the weather. If your API key is set up correctly, you'll get a response in Studio.
+Open [Studio at localhost:4111](http://localhost:4111), select the agent, and send a message. Add the provider API key named in `.env.example` to an `.env` file if you skipped it during setup.
 
-[Studio](https://mastra.ai/docs/studio/overview) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your app using the guides below.
+[Studio](https://mastra.ai/docs/studio/overview) lets you build and test agents without creating a separate UI.
 
 ## Next steps
 
-- Integrate Mastra with your frontend framework: [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
-- Read more about [Mastra's features](https://mastra.ai/docs)
-- Learn how you can [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
-- Build an agent from scratch following one of our [guides](https://mastra.ai/guides)
-- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)
+- Integrate Mastra with [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
+- Learn how to [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
+- Build an agent from scratch with a [guide](https://mastra.ai/guides)
+- Watch the [Mastra YouTube channel](https://www.youtube.com/@mastra-ai)

package/.docs/guides/index.md

@@ -6,7 +6,7 @@ Mastra offers a variety of guides to help you build and work with Mastra, from b
 
 ## New project
 
-The `create mastra` command is the fastest way to build your first agent. It walks you through setup and generates an example agent you can run and adapt in [Studio](https://mastra.ai/docs/studio/overview) right away. You can always integrate Mastra with your framework or UI when you’re ready.
+The `npm create mastra@latest` command is the fastest way to build your first agent. It creates a ready-to-run agent harness that you can explore and adapt in [Studio](https://mastra.ai/docs/studio/overview) right away. You can always integrate Mastra with your framework or UI when you’re ready.
 
 - [Quickstart](https://mastra.ai/guides/getting-started/quickstart)
 

package/.docs/guides/migrations/vnext-to-standard-apis.md

@@ -245,9 +245,7 @@ The following options are available in the standard `.stream()` and `generate()`
   const result = await agent.stream(messages, {
     prepareStep: ({ step, state }) => {
       console.log('About to execute step:', step)
-      return {
-        /* modified state */
-      }
+      return {/* modified state */}
     },
   })
   ```