@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.25

package/.docs/reference/acp/acp-agent.md

@@ -76,6 +76,8 @@ export const claudeCodeAgent = new AcpAgent({
 
 **onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
 
+**createClient** (`(defaultClient: Client) => Client`): Customize the ACP client used to answer agent requests. Receives the default client so it can be wrapped or extended, for example with extMethod and extNotification handlers. See Extension methods.
+
 **workspace** (`Workspace`): Workspace used for ACP file read and write requests. Defaults to a Workspace backed by LocalFilesystem at cwd or process.cwd().
 
 **model** (`ModelId`): Model ID to select after ACP session creation using the ACP session/set\_model method.

package/.docs/reference/acp/create-acp-tool.md

@@ -57,6 +57,8 @@ export const codeSupervisor = new Agent({
 
 **onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
 
+**createClient** (`(defaultClient: Client) => Client`): Customize the ACP client used to answer agent requests. Receives the default client so it can be wrapped or extended, for example with extMethod and extNotification handlers.
+
 **workspace** (`Workspace`): Workspace option from the shared ACP connection options. During tool execution, createACPTool() passes the current Mastra workspace from the execution context when one is available; otherwise the ACP connection falls back to a local filesystem workspace. Use AcpAgent when you need to provide an explicit workspace instance.
 
 **model** (`ModelId`): Model ID to select after ACP session creation using the ACP session/set\_model method.
@@ -124,6 +126,32 @@ export const codeAgentTool = createACPTool({
 
 Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
 
+## Extension methods
+
+Some ACP agents call custom extension methods on the client, outside the standard ACP request set. The default client rejects unknown methods with a "Method not found" error, which can abort the agent's turn.
+
+Pass `createClient` to extend or replace the default client. The callback receives the default client and returns the client used for the connection:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+
+export const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  createClient: defaultClient =>
+    Object.assign(defaultClient, {
+      async extMethod(method: string, params: Record<string, unknown>) {
+        return {}
+      },
+      async extNotification(method: string, params: Record<string, unknown>) {},
+    }),
+})
+```
+
+Return a fully custom `Client` implementation when you need to change the standard handlers as well. The `Client` type is re-exported from `@mastra/acp`.
+
 ## Related
 
 - [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)

package/.docs/reference/agent-controller/session.md

@@ -57,6 +57,19 @@ The session is organized into sub-objects, each owning one domain of per-convers
 
 ## Methods
 
+### Workspace
+
+#### `getWorkspace()`
+
+Return the workspace resolved for this session. This preserves session-level overrides and workspaces selected from the session scope.
+
+```typescript
+const workspace = agentController.session.getWorkspace()
+const skill = await workspace.skills?.get('code-review')
+```
+
+Returns: `Workspace`
+
 ### Permissions
 
 Session-scoped grants auto-approve tools without prompting. Grants are ephemeral — they reset when the session restarts and are never persisted.
@@ -211,6 +224,8 @@ Retrieve messages for a specific thread.
 const messages = await agentController.session.thread.listMessages({ threadId: 'thread-abc123' })
 ```
 
+The message-reading methods `listActiveMessages`, `listMessages`, and `firstUserMessage` return `MastraDBMessage` objects, while `firstUserMessages` returns a `Map<string, MastraDBMessage>` keyed by thread ID. Each message has a `role`, an `id`, a `createdAt`, and a `content` object with `content.format` and a `content.parts` array. Read text, reasoning, tool calls, and attachments from `content.parts`. Signals such as system reminders and notifications are returned as separate messages with `role: 'signal'`.
+
 ### `session.thread.firstUserMessage({ threadId })`
 
 Retrieve the first user message for a thread, or `null` if none.

package/.docs/reference/agents/agent.md

@@ -96,6 +96,18 @@ export const agent = new Agent({
 })
 ```
 
+## Model strings
+
+For the simplest setup, pass `model` as a string in `provider/model` format. Separate the provider and model name with a slash. Mastra reads the matching provider credentials from the environment, so this format doesn't require a provider package or import.
+
+Popular provider strings and credentials:
+
+- **OpenAI**: `openai/gpt-5.5` uses `OPENAI_API_KEY`.
+- **Anthropic**: `anthropic/claude-sonnet-4-6` uses `ANTHROPIC_API_KEY`.
+- **Google**: `google/gemini-2.5-pro` uses `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY`.
+
+See [models](https://mastra.ai/models) for supported model IDs and [environment variables](https://mastra.ai/models/environment-variables) for the complete provider list.
+
 ## Thread signals
 
 Use Agent signals to send real-time input and context into a memory thread. Message APIs are for user-authored input. `sendSignal()` is the lower-level API for system-generated context.
@@ -435,7 +447,7 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **instructions** (`SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>`): Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, array of system messages, or a function that returns any of these types dynamically. SystemMessage types: string | string\[] | CoreSystemMessage | CoreSystemMessage\[] | SystemModelMessage | SystemModelMessage\[]
 
-**model** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>`): The language model used by the agent. Can be provided statically or resolved at runtime.
+**model** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>`): The language model used by the agent. Pass a model router string in provider/model format, a model configuration or provider instance, or a function that resolves the model at runtime. See Model strings for common providers and environment variables.
 
 **agents** (`Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>`): Subagents that the agent can access. Can be provided statically or resolved dynamically.
 

package/.docs/reference/agents/durable-agent.md

@@ -37,6 +37,29 @@ const text = await output.text
 cleanup()
 ```
 
+### Using the `durable` config flag
+
+Set `durable: true` on `AgentConfig` and the agent is automatically wrapped with `createDurableAgent` when it is attached to a `Mastra` instance. Use an object to forward advanced options such as `cache`, `pubsub`, `maxSteps`, or `cleanupTimeoutMs`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+
+const myAgent = new Agent({
+  id: 'my-agent',
+  name: 'My Agent',
+  instructions: 'You are a helpful assistant',
+  model: 'openai/gpt-5.5',
+  durable: true, // or: { maxSteps: 10, cleanupTimeoutMs: 60_000 }
+})
+
+export const mastra = new Mastra({
+  agents: { myAgent },
+})
+```
+
+`mastra.getAgent('myAgent')` returns the wrapped `DurableAgent`. Standalone agents (constructed but never registered on a `Mastra` instance) do not become durable; the wrapping is applied at registration.
+
 ## `createDurableAgent(options)`
 
 Wraps an `Agent` with durable execution and resumable streams. This is the recommended way to create a `DurableAgent`.

package/.docs/reference/agents/generate.md

@@ -106,7 +106,7 @@ const result = await agent.generate('message for agent')
 
 **options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
 
-**options.structuredOutput.jsonPromptInjection** (`boolean`): Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.
+**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the JSON schema reaches the model. Set to 'auto' to use native structured output when supported and inline prompt injection otherwise.
 
 **options.structuredOutput.logger** (`IMastraLogger`): Optional logger instance for structured logging during output generation.
 
@@ -132,6 +132,8 @@ const result = await agent.generate('message for agent')
 
 **options.memory.options** (`MemoryConfig`): Additional memory configuration options including lastMessages, readOnly, semanticRecall, workingMemory, and filterIncompleteToolCalls.
 
+**options.memory.onTitleGenerated** (`(title: string) => void | Promise<void>`): Callback fired asynchronously when a thread title is generated and persisted to storage. Title generation runs in the background and may complete after generate() returns. Only fires when generateTitle is enabled in memory options and the thread has no existing title.
+
 **options.onFinish** (`LoopConfig['onFinish']`): Callback fired when generation completes.
 
 **options.onStepFinish** (`LoopConfig['onStepFinish']`): Callback fired after each generation step.
@@ -456,4 +458,20 @@ const response = await agent.generate('Help me organize my day', {
     console.log({ text, toolCalls, toolResults, finishReason, usage })
   },
 })
+```
+
+### Using `onTitleGenerated`
+
+When `generateTitle` is enabled in memory options, title generation runs asynchronously after the response completes. Use `onTitleGenerated` to react when the title is ready — for example, to push it to the client via SSE.
+
+```typescript
+const response = await agent.generate('What is quantum computing?', {
+  memory: {
+    thread: threadId,
+    resource: userId,
+    onTitleGenerated: title => {
+      console.log('Thread title:', title)
+    },
+  },
+})
 ```

package/.docs/reference/browser/firecrawl-browser.md

@@ -0,0 +1,71 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# FirecrawlBrowser class
+
+The `FirecrawlBrowser` class provides browser automation backed by the [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser). It provisions remote browser sessions through the Firecrawl API and connects to them over the Chrome DevTools Protocol (CDP).
+
+`FirecrawlBrowser` extends [`AgentBrowser`](https://mastra.ai/reference/browser/agent-browser) and exposes the same deterministic toolset. Use it when you want hosted browser sessions instead of a local Chromium install. For local automation, see [`AgentBrowser`](https://mastra.ai/reference/browser/agent-browser). For AI-powered interactions using natural language, see [`StagehandBrowser`](https://mastra.ai/reference/browser/stagehand-browser).
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { FirecrawlBrowser } from '@mastra/browser-firecrawl'
+
+const browser = new FirecrawlBrowser({
+  apiKey: process.env.FIRECRAWL_API_KEY,
+  firecrawl: {
+    ttl: 600,
+  },
+})
+
+export const browserAgent = new Agent({
+  id: 'browser-agent',
+  name: 'Browser Agent',
+  instructions: `You can browse the web. Use browser_snapshot to see the page structure,
+then interact with elements using their refs (e.g., @e5).`,
+  model: 'openai/gpt-5.5',
+  browser,
+})
+```
+
+## Constructor parameters
+
+`FirecrawlBrowser` accepts all [`AgentBrowser` constructor parameters](https://mastra.ai/reference/browser/agent-browser) plus the following:
+
+**apiKey** (`string`): Firecrawl API key. Falls back to the FIRECRAWL\_API\_KEY environment variable. The constructor throws if neither is set.
+
+**apiUrl** (`string`): Base URL for a self-hosted Firecrawl API.
+
+**firecrawl** (`FirecrawlBrowserSessionOptions`): Session options passed to the Firecrawl browser() API when creating sandbox sessions.
+
+**firecrawl.ttl** (`number`): Maximum session lifetime in seconds.
+
+**firecrawl.activityTtl** (`number`): Idle timeout in seconds before the sandbox recycles the session.
+
+**firecrawl.streamWebView** (`boolean`): When true, Firecrawl may stream WebView frames for the remote session.
+
+**firecrawl.profile** (`{ name: string; saveChanges?: boolean }`): Named Firecrawl sandbox profile. Set saveChanges: true to persist cookies and login state when the session ends; naming a profile alone does not save changes. Distinct from the top-level AgentBrowser profile option, which is a local Playwright user-data directory path.
+
+**firecrawl.integration** (`string`): Integration label for Firecrawl analytics and routing.
+
+**firecrawl.origin** (`string`): Origin hint for the Firecrawl browser session.
+
+## Session lifecycle
+
+Session provisioning depends on the `scope` option inherited from `AgentBrowser`:
+
+- `'thread'` (default): Each conversation thread gets its own Firecrawl sandbox session, created on first use and deleted when the thread's browser session is destroyed.
+- `'shared'`: One Firecrawl sandbox session is created when the browser launches and shared across all threads. The session is deleted when the browser closes.
+
+In both cases, `FirecrawlBrowser` deletes the remote Firecrawl session when the browser closes, including when session creation or connection fails partway through.
+
+## Tools
+
+`FirecrawlBrowser` provides the same toolset as `AgentBrowser`, including `browser_goto`, `browser_snapshot`, `browser_click`, `browser_type`, and `browser_screenshot`. See the [`AgentBrowser` tool reference](https://mastra.ai/reference/browser/agent-browser) for the full list and tool parameters.
+
+## Related
+
+- [Firecrawl docs](https://mastra.ai/docs/browser/firecrawl)
+- [`AgentBrowser` reference](https://mastra.ai/reference/browser/agent-browser)
+- [Browser overview](https://mastra.ai/docs/browser/overview)

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

@@ -2,9 +2,7 @@
 
 # create-mastra
 
-The `create-mastra` command **creates** a new standalone Mastra project. Use this command to scaffold a complete Mastra setup in a dedicated directory. You can run it with additional flags to customize the setup process.
-
-## Usage
+Create a standalone Mastra project. By default, `create-mastra` installs a default starter and configures it for your selected model provider.
 
 **npm**:
 
@@ -30,116 +28,193 @@ yarn dlx create-mastra@latest
 bun x create-mastra@latest
 ```
 
-`create-mastra` automatically runs in _interactive_ mode, but you can also specify your project name and template with command line arguments.
+## Creation modes
+
+### Default starter
+
+The default starter creates an agent harness with workspace tools, memory, task tracking, web access, recurring schedules, storage, and observability. Select OpenAI, Anthropic, Gemini, or xAI as your model provider.
+
+Provide both the project name and provider to create the project without prompts. This example uses Anthropic; you can also pass `openai`, `google`, or `xai`:
 
 **npm**:
 
 ```bash
-npx create-mastra@latest my-mastra-project -- --template coding-agent
+npx create-mastra@latest my-mastra-project --llm anthropic
 ```
 
 **pnpm**:
 
 ```bash
-pnpm dlx create-mastra@latest my-mastra-project -- --template coding-agent
+pnpm dlx create-mastra@latest my-mastra-project --llm anthropic
 ```
 
 **Yarn**:
 
 ```bash
-yarn dlx create-mastra@latest my-mastra-project -- --template coding-agent
+yarn dlx create-mastra@latest my-mastra-project --llm anthropic
 ```
 
 **Bun**:
 
 ```bash
-bun x create-mastra@latest my-mastra-project -- --template coding-agent
+bun x create-mastra@latest my-mastra-project --llm anthropic
+```
+
+Omit `--llm` to select the provider and optionally enter its API key interactively. The interactive setup also offers to connect your project to the Mastra platform. If enabled, the command opens the browser authentication flow, creates a platform project with the same name as the local project, and writes `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`.
+
+### Template
+
+Use a template slug or a public GitHub URL:
+
+**npm**:
+
+```bash
+npx create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**Yarn**:
+
+```bash
+yarn dlx create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**Bun**:
+
+```bash
+bun x create-mastra@latest my-mastra-project --template agent-harness
+```
+
+**npm**:
+
+```bash
+npx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
 ```
 
-Check out the [full list](https://mastra.ai/api/templates.json) of templates and use the `slug` as input to the `--template` CLI flag.
+**Yarn**:
 
-You can also use any GitHub repo as a template (it has to be a valid Mastra project):
+```bash
+yarn dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
+```
+
+**Bun**:
 
 ```bash
-npx create-mastra@latest my-mastra-project -- --template mastra-ai/template-coding-agent
+bun x create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
 ```
 
-You can install Mastra skills for specific agents during project creation:
+Leave the template value blank to select a template interactively:
 
 **npm**:
 
 ```bash
-npx create-mastra@latest my-project -- --default --skills claude-code,cursor
+npx create-mastra@latest my-mastra-project --template
 ```
 
 **pnpm**:
 
 ```bash
-pnpm dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
+pnpm dlx create-mastra@latest my-mastra-project --template
 ```
 
 **Yarn**:
 
 ```bash
-yarn dlx create-mastra@latest my-project -- --default --skills claude-code,cursor
+yarn dlx create-mastra@latest my-mastra-project --template
 ```
 
 **Bun**:
 
 ```bash
-bun x create-mastra@latest my-project -- --default --skills claude-code,cursor
+bun x create-mastra@latest my-mastra-project --template
 ```
 
-## CLI flags
+Template authors own their dependencies, models, environment variables, and source code. `create-mastra` doesn't apply `--llm` or `--llm-api-key`.
 
-Instead of an interactive prompt you can also define these CLI flags.
+### Empty scaffold
 
-**--version** (`boolean`): Output the version number
+Use `--empty` to create a provider-free project without agents, examples, model SDKs, or environment files:
 
-**--project-name** (`string`): Project name that will be used in package.json and as the project directory name
+**npm**:
 
-**--default** (`boolean`): Quickstart with defaults (src, OpenAI, no examples)
+```bash
+npx create-mastra@latest my-empty-project --empty
+```
 
-**--components** (`string`): Comma-separated list of components (agents, tools, workflows, scorers)
+**pnpm**:
 
-**--llm** (`string`): Default model provider (openai, anthropic, groq, google, or cerebras)
+```bash
+pnpm dlx create-mastra@latest my-empty-project --empty
+```
 
-**--llm-api-key** (`string`): API key for the model provider
+**Yarn**:
 
-**--example** (`boolean`): Include example code
+```bash
+yarn dlx create-mastra@latest my-empty-project --empty
+```
+
+**Bun**:
 
-**--no-example** (`boolean`): Do not include example code
+```bash
+bun x create-mastra@latest my-empty-project --empty
+```
 
-**--template** (`string`): Create project from a template (use template name, public GitHub URL, or leave blank to select from list)
+## Automatic setup
 
-**--timeout** (`number`): Configurable timeout for package installation, defaults to 60000 ms
+After installing dependencies, the command:
 
-**--dir** (`string`): Target directory for Mastra source code (default: src/)
+1. Detects supported coding assistants on `PATH` and installs Mastra skills. If none are detected, it installs universal skills.
+2. Creates an initial Git commit when the current directory and generated project aren't already inside Git repositories.
 
-**--mcp** (`string`): MCP Server for code editor (cursor, cursor-global, windsurf, vscode)
+Use `--no-skills` or `--no-git` to skip these steps. Skills and Git setup failures produce warnings but don't remove a successfully created project.
 
-**--skills** (`string`): Comma-separated list of agents to install Mastra skills for (e.g., claude-code,cursor,windsurf)
+## Conflicts and validation
 
-**--observability** (`boolean`): Enable Observability on the Mastra platform during project creation. This opens browser login when needed, prompts for an organization, provisions a platform project, and configures the observability exporters.
+- `--empty` and `--template` can't be used together.
+- `--llm` and `--llm-api-key` are only valid for the default starter project.
+- The project name must be a safe, lowercase, single directory name and the target must not already exist.
 
-**--no-observability** (`boolean`): Skip the Observability prompt during project creation.
+Invalid input is rejected before templates are fetched or files are created.
 
-**--observability-project** (`string`): Set the platform project name to use when Mastra Observability is enabled.
+## Arguments and flags
 
-**--help** (`boolean`): Display help for command
+**\[project-name]** (`string`): Project directory and package name. When omitted, the command prompts for it.
 
-## Telemetry
+**--empty** (`boolean`): Create a minimal, provider-free Mastra project.
 
-By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
+**-l, --llm \<provider>** (`string`): Managed agent-harness provider: openai, anthropic, google, or xai.
 
-You can opt out of the CLI analytics by setting an environment variable:
+**-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file.
 
-```bash
-MASTRA_TELEMETRY_DISABLED=1
-```
+**--no-skills** (`boolean`): Skip automatic Mastra skills installation.
+
+**--no-git** (`boolean`): Skip automatic Git initialization and the initial commit.
+
+**-t, --template \[template]** (`string`): Use a template slug or public GitHub URL. Omit the value to select interactively.
+
+**--timeout \<milliseconds>** (`number`): Positive integer timeout for dependency installation. Defaults to 60000.
+
+**--version** (`boolean`): Print the create-mastra version.
+
+**--help** (`boolean`): Display command help.
+
+## Telemetry
+
+Mastra collects anonymous CLI usage information, such as the operating system, Mastra version, and Node.js version. You can review the [analytics source](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts).
 
-You can also set this while using other `mastra` commands:
+Set `MASTRA_TELEMETRY_DISABLED=1` to opt out:
 
 ```bash
-MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest
+MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest my-project --empty
 ```

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

@@ -101,6 +101,18 @@ mastra dev
 
 These are forwarded to the Mastra model router and will work with any `"openai/..."` or `"anthropic/..."` model selections.
 
+## `mastra factory dev`
+
+Starts a development server for [Agent Builder](https://mastra.ai/docs/agent-builder/overview) development. It uses the same dev runtime and flags as [`mastra dev`](#mastra-dev) and writes to the same `.mastra/output` directory.
+
+```bash
+npx mastra factory dev
+```
+
+Both commands share the same dev lock, so `mastra dev` and `mastra factory dev` can't run simultaneously in the same project. If one is already running, the other exits with a duplicate development server error.
+
+Use `mastra factory dev` when developing Agent Builder features. It accepts the same flags as [`mastra dev`](#mastra-dev), including `--https`, `--inspect`, `--inspect-brk`, `--custom-args`, and `--request-context-presets`.
+
 ## `mastra build`
 
 The `mastra build` command bundles your Mastra project into a production-ready Hono server. [Hono](https://hono.dev/) is a lightweight, type-safe web framework that makes it straightforward to deploy Mastra agents as HTTP endpoints with middleware support.
@@ -361,7 +373,7 @@ File to write. Defaults to `.env`.
 
 Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.
 
-A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Pass the environment argument to work with environment-scoped databases; omit it for shared databases.
+A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Environment-scoped is the default for `mastra env db create` — pass an environment argument, or let the CLI pick or prompt for one. Pass `--shared` on create to attach a shared database instead. For other subcommands (`list`, `delete`, `keys`), pass the environment argument to work with environment-scoped databases and omit it for shared databases.
 
 Creating and deleting databases requires the `admin` role in the organization.
 
@@ -382,11 +394,15 @@ Emit machine-readable JSON.
 
 Provisions a managed database, attaches it, and polls until it's ready. Provisioning errors are printed with the provider's error detail.
 
-With an environment argument, the database is scoped to that environment: only it receives the database's connection env vars, and the provider region is derived from the environment's region. Without one, the database is shared by all environments.
+By default the database is scoped to a single environment: pass an environment argument to pick it, or omit the argument to have the CLI pick for you. When the project has one environment, that environment is used. When it has several, the CLI prompts you to select one interactively; in non-interactive contexts (CI, `--json`) an environment argument is required. Pass `--shared` to attach a project-scoped database that's shared by every environment instead.
+
+Environment-scoped databases inherit their provider region from the environment. Shared databases accept `--region`.
 
 ```bash
-mastra env db create <env> --kind turso
-mastra env db create --kind neon --name my-app-db --region aws-us-east-1
+mastra env db create --kind turso                                    # picks or prompts for an environment
+mastra env db create staging --kind turso                            # scoped to the "staging" environment
+mastra env db create --kind turso --shared                           # shared by all environments
+mastra env db create --kind neon --name my-app-db --region aws-us-east-1 --shared
 ```
 
 #### `--kind`
@@ -401,13 +417,17 @@ Database name. Defaults to a name derived from the project slug (for example `my
 
 Provider region ID for shared databases. Ignored for environment-scoped databases.
 
+#### `--shared`
+
+Attach as a project-scoped database that's shared by every environment. Cannot be combined with an environment argument.
+
 #### `--no-wait`
 
 Return immediately after the attach is queued instead of polling until the database is ready. Check progress later with `mastra env db show`.
 
 #### `--json`
 
-Emit machine-readable JSON.
+Emit machine-readable JSON. In this mode, an environment argument or `--shared` is required when the project has more than one environment (no interactive prompt).
 
 ### `mastra env db show`
 
@@ -796,6 +816,40 @@ Use the [`list`](#list) command to get the correct ID.
 
 List all available scorer templates. Use the ID for the `add` command.
 
+## `mastra create`
+
+Create a standalone Mastra project with the same project-creation flow as [`create-mastra`](https://mastra.ai/reference/cli/create-mastra).
+
+**npm**:
+
+```bash
+npx mastra@latest create
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra@latest create
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra@latest create
+```
+
+**Bun**:
+
+```bash
+bun x mastra@latest create
+```
+
+Providing both the project name and `--llm` skips the interactive setup prompts. Use `--template [template]` for an arbitrary template or `--empty` for a minimal provider-free scaffold.
+
+The command installs Mastra skills for detected coding assistants and initializes Git when appropriate. Use `--no-skills` or `--no-git` to opt out.
+
+See the [`create-mastra` reference](https://mastra.ai/reference/cli/create-mastra) for mode behavior, conflicts, validation, and complete flag descriptions.
+
 ## `mastra init`
 
 The `mastra init` command initializes Mastra in an existing project. Use this command to scaffold the necessary folders and configuration without generating a new project from scratch.

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -4,7 +4,7 @@
 
 > **Beta:** The `@mastra/code-sdk` package is experimental and subject to breaking changes in minor versions.
 
-The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller — the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management — and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller (the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management) and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 To construct the `Mastra` instance yourself (for example in a deployable entry file), use `prepareAgentControllerMount()` from the same package, which returns the constructor args plus a `finalize()` callback.
 
@@ -27,9 +27,7 @@ Pass an existing `mastra` to mount the controller onto a Mastra instance that al
 import { Mastra } from '@mastra/core/mastra'
 import { mountAgentControllerOnMastra } from '@mastra/code-sdk'
 
-const mastra = new Mastra({
-  /* ... */
-})
+const mastra = new Mastra({/* ... */})
 
 const { controller } = await mountAgentControllerOnMastra({ mastra })
 ```
@@ -50,6 +48,8 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
 
 **postToolObserver** (`(context: ToolAfterHookContext) => void | Promise<void>`): Observes completed tool calls without replacing the tool or changing hook-manager behavior. Observer errors are logged and do not fail successful tool calls.
 
+**inputProcessors** (`InputProcessor[]`): Stateless input processors prepended before Mastra Code's mandatory safety and compatibility processors. Custom processors extend the pipeline but can't replace the built-in processors.
+
 **disabledTools** (`string[]`): Tools removed from the dynamic tool set before exposure to the model.
 
 **storage** (`StorageConfig`): Custom storage config instead of the auto-detected default.

package/.docs/reference/core/getMCPServer.md

@@ -12,9 +12,7 @@ const myServer = new MCPServer({
   id: 'my-mcp-server',
   name: 'My Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 
 export const mastra = new Mastra({