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

package/.docs/models/providers/privatemode-ai.md

@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "privatemode-ai/gemma-3-27b"
+  model: "privatemode-ai/gpt-oss-120b"
 });
 
 // Generate a response
@@ -34,13 +34,13 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `privatemode-ai/gemma-3-27b`         | 128K    |       |           |       |       |       | —          | —           |
-| `privatemode-ai/gpt-oss-120b`        | 128K    |       |           |       |       |       | —          | —           |
-| `privatemode-ai/qwen3-coder-30b-a3b` | 128K    |       |           |       |       |       | —          | —           |
-| `privatemode-ai/qwen3-embedding-4b`  | 32K     |       |           |       |       |       | —          | —           |
-| `privatemode-ai/whisper-large-v3`    | —       |       |           |       |       |       | —          | —           |
+| Model                               | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ----------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `privatemode-ai/gpt-oss-120b`       | 128K    |       |           |       |       |       | —          | —           |
+| `privatemode-ai/kimi-k2.6`          | 262K    |       |           |       |       |       | —          | —           |
+| `privatemode-ai/qwen3-embedding-4b` | 32K     |       |           |       |       |       | —          | —           |
+| `privatemode-ai/voxtral-mini-3b`    | 32K     |       |           |       |       |       | —          | —           |
+| `privatemode-ai/whisper-large-v3`   | —       |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -52,7 +52,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "http://localhost:8080/v1",
-    id: "privatemode-ai/gemma-3-27b",
+    id: "privatemode-ai/gpt-oss-120b",
     apiKey: process.env.PRIVATEMODE_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -71,7 +71,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "privatemode-ai/whisper-large-v3"
-      : "privatemode-ai/gemma-3-27b";
+      : "privatemode-ai/gpt-oss-120b";
   }
 });
 ```

package/.docs/models/providers/thinkingmachines.md

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![Thinking Machines logo](https://models.dev/logos/thinkingmachines.svg)Thinking Machines
+
+Access 1 Thinking Machines model through Mastra's model router. Authentication is handled automatically using the `TINKER_API_KEY` environment variable.
+
+Learn more in the [Thinking Machines documentation](https://tinker-docs.thinkingmachines.ai/tinker/compatible-apis/openai/).
+
+```bash
+TINKER_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "thinkingmachines/inkling"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Thinking Machines documentation](https://tinker-docs.thinkingmachines.ai/tinker/compatible-apis/openai/) for details.
+
+## Models
+
+| Model                      | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| -------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `thinkingmachines/inkling` | 256K    |       |           |       |       |       | $4         | $9          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://tinker.thinkingmachines.dev/services/tinker-prod/oai/api/v1",
+    id: "thinkingmachines/inkling",
+    apiKey: process.env.TINKER_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "thinkingmachines/inkling"
+      : "thinkingmachines/inkling";
+  }
+});
+```

package/.docs/models/providers/togetherai.md

@@ -2,7 +2,7 @@
 
 # ![Together AI logo](https://models.dev/logos/togetherai.svg)Together AI
 
-Access 25 Together AI models through Mastra's model router. Authentication is handled automatically using the `TOGETHER_API_KEY` environment variable.
+Access 21 Together AI models through Mastra's model router. Authentication is handled automatically using the `TOGETHER_API_KEY` environment variable.
 
 Learn more in the [Together AI documentation](https://docs.together.ai/docs/serverless-models).
 
@@ -36,7 +36,6 @@ for await (const chunk of stream) {
 | ----------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `togetherai/deepcogito/cogito-v2-1-671b`              | 164K    |       |           |       |       |       | $1         | $1          |
 | `togetherai/deepseek-ai/DeepSeek-V4-Pro`              | 512K    |       |           |       |       |       | $2         | $3          |
-| `togetherai/essentialai/Rnj-1-Instruct`               | 33K     |       |           |       |       |       | $0.15      | $0.15       |
 | `togetherai/google/gemma-3n-E4B-it`                   | 33K     |       |           |       |       |       | $0.06      | $0.12       |
 | `togetherai/google/gemma-4-31B-it`                    | 262K    |       |           |       |       |       | $0.39      | $0.97       |
 | `togetherai/LiquidAI/LFM2-24B-A2B`                    | 33K     |       |           |       |       |       | $0.03      | $0.12       |
@@ -51,13 +50,10 @@ for await (const chunk of stream) {
 | `togetherai/openai/gpt-oss-20b`                       | 131K    |       |           |       |       |       | $0.05      | $0.20       |
 | `togetherai/pearl-ai/gemma-4-31b-it`                  | 32K     |       |           |       |       |       | $0.28      | $0.86       |
 | `togetherai/Qwen/Qwen2.5-7B-Instruct-Turbo`           | 33K     |       |           |       |       |       | $0.30      | $0.30       |
-| `togetherai/Qwen/Qwen3-235B-A22B-Instruct-2507-tput`  | 262K    |       |           |       |       |       | $0.20      | $0.60       |
-| `togetherai/Qwen/Qwen3.5-397B-A17B`                   | 262K    |       |           |       |       |       | $0.60      | $4          |
 | `togetherai/Qwen/Qwen3.5-9B`                          | 262K    |       |           |       |       |       | $0.17      | $0.25       |
 | `togetherai/Qwen/Qwen3.6-Plus`                        | 1.0M    |       |           |       |       |       | $0.50      | $3          |
 | `togetherai/Qwen/Qwen3.7-Max`                         | 1.0M    |       |           |       |       |       | $1         | $4          |
-| `togetherai/zai-org/GLM-5`                            | 203K    |       |           |       |       |       | $1         | $3          |
-| `togetherai/zai-org/GLM-5.1`                          | 203K    |       |           |       |       |       | $1         | $4          |
+| `togetherai/thinkingmachines/Inkling`                 | 524K    |       |           |       |       |       | $1         | $4          |
 | `togetherai/zai-org/GLM-5.2`                          | 262K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration

package/.docs/models/providers/zenmux.md

@@ -2,7 +2,7 @@
 
 # ![ZenMux logo](https://models.dev/logos/zenmux.svg)ZenMux
 
-Access 118 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
+Access 119 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
 
 Learn more in the [ZenMux documentation](https://docs.zenmux.ai).
 
@@ -83,6 +83,7 @@ for await (const chunk of stream) {
 | `zenmux/moonshotai/kimi-k2.6`                 | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `zenmux/moonshotai/kimi-k2.7-code`            | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `zenmux/moonshotai/kimi-k2.7-code-free`       | 262K    |       |           |       |       |       | —          | —           |
+| `zenmux/moonshotai/kimi-k3`                   | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `zenmux/openai/gpt-5`                         | 400K    |       |           |       |       |       | $1         | $10         |
 | `zenmux/openai/gpt-5-codex`                   | 400K    |       |           |       |       |       | $1         | $10         |
 | `zenmux/openai/gpt-5.1`                       | 400K    |       |           |       |       |       | $1         | $10         |

package/.docs/models/providers.md

@@ -131,6 +131,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Tencent Token Plan](https://mastra.ai/models/providers/tencent-token-plan)
 - [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)
 - [The Grid AI](https://mastra.ai/models/providers/the-grid-ai)
+- [Thinking Machines](https://mastra.ai/models/providers/thinkingmachines)
 - [Tinfoil](https://mastra.ai/models/providers/tinfoil)
 - [Together AI](https://mastra.ai/models/providers/togetherai)
 - [TrustedRouter](https://mastra.ai/models/providers/trustedrouter)

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/agent-controller-class.md

@@ -22,7 +22,7 @@ import { z } from 'zod'
 const agentController = new AgentController({
   id: 'my-coding-agent',
   agent: myAgent,
-  storage: new LibSQLStore({ url: 'file:./data.db' }),
+  storage: new LibSQLStore({ id: 'agent-storage', url: 'file:./data.db' }),
   stateSchema: z.object({
     currentModelId: z.string().optional(),
   }),

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,11 +447,11 @@ 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.
 
-**tools** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
+**tools** (`ToolsInput | ({ requestContext: RequestContext, mastra?: Mastra }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically from the request context and associated Mastra instance when available.
 
 **hooks** (`ToolHooks`): Hooks that run before and after every tool call made by this agent. Per-execution hooks passed to generate() or stream() override matching hooks set here. See Tool hooks below.
 

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

@@ -361,7 +361,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 +382,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 +405,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`
 
@@ -429,7 +437,7 @@ Emit machine-readable JSON. Secret values are masked unless `--show-secrets` is
 
 ### `mastra env db delete`
 
-Permanently deletes a database with the provider, including all of its data. This cannot be undone. The CLI prompts for confirmation unless `--yes` is passed. After deletion, deploys no longer receive the database's env vars.
+Permanently deletes a database with the provider, including all of its data. This can't be undone. The CLI prompts for confirmation unless `--yes` is passed. After deletion, deploys no longer receive the database's env vars.
 
 ```bash
 mastra env db delete <database>

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

@@ -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 })
 ```

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({

package/.docs/reference/core/getMCPServerById.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({

package/.docs/reference/core/getTool.md

@@ -0,0 +1,33 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.getTool()
+
+The `.getTool()` method retrieves a tool from the Mastra-level registry by its registration key.
+
+## Usage example
+
+Register a tool under the `weather` key, then use that key to retrieve it.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { weatherTool } from './tools/weather-tool'
+
+export const mastra = new Mastra({
+  tools: {
+    weather: weatherTool,
+  },
+})
+
+const tool = mastra.getTool('weather')
+```
+
+## Parameters
+
+**name** (`TToolName extends keyof TTools`): The registration key of the tool in the Mastra tools registry.
+
+## Related
+
+- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)
+- [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/getToolById.md

@@ -0,0 +1,48 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mastra.getToolById()
+
+The `.getToolById()` method first searches the Mastra-level registry for a tool with a matching intrinsic `id`. If no intrinsic ID matches, it treats the value as a registration key.
+
+## Usage example
+
+This example uses `weather` as the registration key and `weather-tool` as the tool's intrinsic ID.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    weather: z.string(),
+  }),
+  execute: async ({ location }) => ({
+    weather: `Weather for ${location}`,
+  }),
+})
+
+export const mastra = new Mastra({
+  tools: {
+    weather: weatherTool,
+  },
+})
+
+const toolById = mastra.getToolById('weather-tool')
+```
+
+## Parameters
+
+**id** (`TTools[TToolName]['id']`): The intrinsic tool ID to find. When no tool has that ID, Mastra uses the value as a registration key.
+
+## Related
+
+- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
+- [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/getWorkflow.md

@@ -13,9 +13,7 @@ const run = await workflow.createRun()
 
 // TypeScript will properly infer the input schema type
 await run.startAsync({
-  inputData: {
-    /* properly typed */
-  },
+  inputData: {/* properly typed */},
 })
 ```