@mastra/mcp-docs-server 1.2.7-alpha.12 → 1.2.7-alpha.3

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

@@ -0,0 +1,297 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# File-based agents
+
+**Added in:** `@mastra/core@1.48.0`
+
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+You can define an agent by file convention instead of constructing it in code. Mastra discovers a directory under `src/mastra/agents/<name>/`, assembles an [`Agent`](https://mastra.ai/reference/agents/agent), and registers it on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
+
+## When to use file-based agents
+
+Use file-based agents when you want one directory per agent, with configuration, instructions, tools, skills, workspace files, and subagents grouped together.
+
+Keep using [`new Agent()`](https://mastra.ai/reference/agents/agent) in code when you need dynamic configuration, programmatic registration, or a shared agent instance across modules. Both approaches can coexist: code-registered agents are always present, and the bundler adds file-based agents when you run through the Mastra CLI.
+
+## Quickstart
+
+Create a directory for the agent and add a `config.ts`. Use `agentConfig` so the partial config is typed while sibling files supply the rest.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  // instructions omitted -> taken from instructions.md
+  // tools omitted -> taken from tools/*.ts
+})
+```
+
+Add the agent instructions:
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+Add a tool. The filename becomes the tool key, so this file is exposed as `get_weather`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export default createTool({
+  id: 'get_weather',
+  description: 'Get the current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+  execute: async ({ context }) => ({ city: context.city, tempC: 21 }),
+})
+```
+
+Your `src/mastra/index.ts` stays the same. The discovered agent is registered automatically when you run the app through `mastra dev` or `mastra build`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+
+const supportAgent = new Agent({
+  id: 'support',
+  name: 'support',
+  instructions: 'You are a support agent.',
+  model: 'openai/gpt-5.5',
+})
+
+// `support` is registered in code; `weather` is discovered from the filesystem.
+export const mastra = new Mastra({
+  agents: { support: supportAgent },
+})
+```
+
+Start the app through the Mastra CLI:
+
+**npm**:
+
+```bash
+npx mastra dev
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra dev
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra dev
+```
+
+**Bun**:
+
+```bash
+bun x mastra dev
+```
+
+## Folder structure
+
+The following table shows the supported file-based agent surface:
+
+| File / directory                        | Maps to                                                                                                                                   |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents/<name>/config.ts`               | Default export merged into the agent config. `id` and `name` default to `<name>`.                                                         |
+| `agents/<name>/instructions.md`         | The agent `instructions`. The file contents are inlined into generated code.                                                              |
+| `agents/<name>/tools/*.ts`              | Each default-exported [`createTool()`](https://mastra.ai/reference/tools/create-tool). The tool key defaults to the filename.             |
+| `agents/<name>/skills/*.ts`             | Each default-exported [`createSkill()`](https://mastra.ai/reference/agents/createSkill), added to the agent `skills`.                     |
+| `agents/<name>/skills/<skill>/SKILL.md` | A packaged skill. Frontmatter supplies `name` and `description`, the body is the instructions, and files under `references/` are inlined. |
+| `agents/<name>/skills/<skill>.md`       | A flat skill. The filename is the skill name and the body is the instructions.                                                            |
+| `agents/<name>/memory.ts`               | Default export: a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance used as the agent `memory`.                        |
+| `agents/<name>/workspace.ts`            | Default export: a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) for the agent.                                     |
+| `agents/<name>/workspace/`              | Seed files mirrored into the agent's default workspace at build time.                                                                     |
+| `agents/<name>/subagents/<childId>/`    | A declared subagent with the same layout as an agent directory. Wired into the parent as a delegation tool named `<childId>`.             |
+
+Test files named `*.test.ts`, `*.spec.ts`, `*.test.js`, and `*.spec.js` are ignored during tool and skill discovery.
+
+## Add skills
+
+Add skills to a file-based agent by placing them under `agents/<name>/skills/`. Three layouts are supported, and they're inlined into the bundle at build time so the deployed agent doesn't read them from disk at runtime.
+
+- A `.ts` file can default-export `createSkill()`:
+
+  ```typescript
+  import { createSkill } from '@mastra/core/skills'
+
+  export default createSkill({
+    name: 'forecasting',
+    description: 'Use when the user asks about multi-day forecasts.',
+    instructions: 'Summarize the forecast day by day and call out precipitation.',
+  })
+  ```
+
+  > **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
+
+- A packaged `SKILL.md` directory uses frontmatter for the name and description. Files under `references/` are inlined with the skill.
+
+  ```markdown
+  ---
+  name: severe-weather
+  description: Use when conditions include storms, flooding, or other hazards.
+  ---
+
+  Lead with the active alert, then give safety guidance.
+  ```
+
+- A flat `<skill>.md` file uses the filename as the skill name:
+
+  ```markdown
+  Always report temperatures in both Celsius and Fahrenheit.
+  ```
+
+Discovered skills merge with any `skills` in `config.ts`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning because they can't be statically merged.
+
+## Add memory
+
+Give a file-based agent [memory](https://mastra.ai/docs/memory/overview) by adding a `memory.ts` that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. You can also set `memory` directly in `config.ts`. `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is present, the agent has no memory, which is the default.
+
+## Add a workspace
+
+When a file-based agent is discovered through `mastra dev` or `mastra build`, it gets a default workspace unless `config.workspace` or `workspace.ts` supplies one. The default workspace uses a contained filesystem and shell sandbox rooted at a per-agent `workspace/` directory in the bundle.
+
+To customize it, add a `workspace.ts` that default-exports a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class):
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+export default new Workspace({
+  name: 'weather-workspace',
+  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
+  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
+})
+```
+
+You can also set `workspace` directly in `config.ts`. `config.workspace` wins over `workspace.ts`, and `workspace.ts` wins over the default workspace.
+
+### Seed files
+
+Add a `workspace/` directory to ship files with the agent. Mastra mirrors every file under it into the agent's default workspace at build time, so the agent starts with those files on disk:
+
+```text
+src/mastra/agents/weather/
+  config.ts
+  workspace/
+    README.md
+    data/cities.json
+```
+
+Seed files are copied into the bundle next to the running server. Commit the starting files alongside the agent that uses them.
+
+## Add subagents
+
+A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `workspace/`.
+
+```text
+src/mastra/agents/
+  supervisor/
+    config.ts
+    instructions.md
+    subagents/
+      researcher/
+        config.ts
+        instructions.md
+        tools/
+          search.ts
+```
+
+Each subagent is assembled as its own agent and wired into the parent's `agents` map. The agent loop lowers it into a model-visible delegation tool. The tool name is the bare directory name, so the example above exposes `researcher` to the supervisor.
+
+A subagent's `config.ts` must set a non-empty `description`. The description is what the model sees when deciding whether to delegate, so the build fails if it's missing.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  description: 'Researches a topic and returns cited findings.',
+})
+```
+
+Subagents are isolated. A subagent inherits nothing from its parent. Its tools, skills, and workspace come only from its own directory, and any absent slot falls back to the same framework defaults as a top-level agent.
+
+Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory deeper than that's ignored with a warning.
+
+```text
+src/mastra/agents/
+  supervisor/            # depth 0
+    subagents/
+      researcher/        # depth 1
+        subagents/
+          summarizer/    # depth 2
+```
+
+Naming rules:
+
+- A subagent id that collides with one of the parent's tool keys is a build error.
+- A duplicate subagent id under the same parent is a build error.
+- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
+- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
+
+## Precedence rules
+
+File-based and code-based agents coexist with deterministic rules:
+
+- **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
+- **A folder can hold a code agent:** If `config.ts` exports a configured `new Agent({ id: 'file-based-agent', ... })`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
+- **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
+- **Model:** A missing `model` fails the build and names the agent directory.
+- **Tools:** Tools from `tools/*.ts` merge with `config.tools`. On a key collision, `config.tools` wins and a warning is logged. If `config.tools` is a function, discovered tools are ignored with a warning.
+- **Skills:** Skills from `skills/` merge with `config.skills`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning.
+- **Memory:** `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is set, the agent has no memory.
+- **Workspace:** `config.workspace` wins over `workspace.ts`, which wins over the default workspace.
+- **Subagents:** Subagents from `subagents/` merge with `config.agents`. On an id collision, `config.agents` wins and a warning is logged. A subagent id that collides with a tool key, or a duplicate subagent id, is a build error.
+
+## What happens at build time
+
+File-based agents are discovered by the Mastra **bundler**, the step that runs under `mastra dev` and `mastra build`.
+
+File-based agents are registered only when your app runs through the Mastra CLI. If you import your `mastra` instance directly, `agents/<name>/` directories aren't discovered.
+
+When you consume Mastra as a library, register those agents in code instead of relying on file discovery:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+
+const weather = new Agent({
+  id: 'weather',
+  name: 'weather',
+  instructions: 'You are a helpful weather assistant.',
+  model: 'openai/gpt-5.5',
+})
+
+export const mastra = new Mastra({
+  agents: { weather },
+})
+```
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Skills](https://mastra.ai/docs/agents/skills)
+- [Memory](https://mastra.ai/docs/memory/overview)
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Workspace](https://mastra.ai/docs/workspace/overview)
+- [Studio overview](https://mastra.ai/docs/studio/overview)
+- [`Agent` reference](https://mastra.ai/reference/agents/agent)
+- [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
+- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/docs/agents/guardrails.md

@@ -29,7 +29,7 @@ export const normalizedAgent = new Agent({
 })
 ```
 
-Visit [`UnicodeNormalizer()`](https://mastra.ai/reference/processors/unicode-normalizer) reference for a full list of configuration options.
+> **Note:** Visit [`UnicodeNormalizer()`](https://mastra.ai/reference/processors/unicode-normalizer) reference for a full list of configuration options.
 
 ### Prevent prompt injection
 
@@ -52,7 +52,7 @@ export const secureAgent = new Agent({
 })
 ```
 
-Visit [`PromptInjectionDetector()`](https://mastra.ai/reference/processors/prompt-injection-detector) reference for a full list of configuration options.
+> **Note:** Visit [`PromptInjectionDetector()`](https://mastra.ai/reference/processors/prompt-injection-detector) reference for a full list of configuration options.
 
 ### Detect and translate language
 
@@ -75,7 +75,7 @@ export const multilingualAgent = new Agent({
 })
 ```
 
-Visit [`LanguageDetector()`](https://mastra.ai/reference/processors/language-detector) reference for a full list of configuration options.
+> **Note:** Visit [`LanguageDetector()`](https://mastra.ai/reference/processors/language-detector) reference for a full list of configuration options.
 
 ## Output processors
 
@@ -101,7 +101,7 @@ export const batchedAgent = new Agent({
 })
 ```
 
-Visit [`BatchPartsProcessor()`](https://mastra.ai/reference/processors/batch-parts-processor) reference for a full list of configuration options.
+> **Note:** Visit [`BatchPartsProcessor()`](https://mastra.ai/reference/processors/batch-parts-processor) reference for a full list of configuration options.
 
 ### Scrub system prompts
 
@@ -128,7 +128,7 @@ const scrubbedAgent = new Agent({
 })
 ```
 
-Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
+> **Note:** Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
 
 > **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/mastra-server) for details.
 
@@ -158,7 +158,7 @@ export const moderatedAgent = new Agent({
 })
 ```
 
-Visit [`ModerationProcessor()`](https://mastra.ai/reference/processors/moderation-processor) reference for a full list of configuration options.
+> **Note:** Visit [`ModerationProcessor()`](https://mastra.ai/reference/processors/moderation-processor) reference for a full list of configuration options.
 
 ### Detect and redact PII
 
@@ -184,7 +184,7 @@ export const privateAgent = new Agent({
 })
 ```
 
-Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) reference for a full list of configuration options.
+> **Note:** Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) reference for a full list of configuration options.
 
 ### Enforce cost limits
 
@@ -206,7 +206,7 @@ export const budgetedAgent = new Agent({
 })
 ```
 
-Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
+> **Note:** Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
 
 ## Processor strategies
 
@@ -386,5 +386,4 @@ outputProcessors: [
 
 - [Processors](https://mastra.ai/docs/agents/processors): How processors work, execution order, custom processors, and retry mechanism
 - [`Processor` Interface](https://mastra.ai/reference/processors/processor-interface): API reference for the `Processor` interface
-- [Memory Processors](https://mastra.ai/docs/memory/memory-processors): Processors for message history, semantic recall, and working memory
-- 📹 [Mastra processors and guardrails workshop](https://www.youtube.com/watch?v=4Vpp7xQYvl0)
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors): Processors for message history, semantic recall, and working memory

package/.docs/docs/agents/overview.md

@@ -119,7 +119,7 @@ console.log(response.text)
 
 Use agents when the task is open-ended and the steps aren't known in advance. An agent decides which tools to call, how many times to loop, and when to stop. You provide the goal and constraints instead of defining each step. For predetermined, multi-step processes with explicit control flow, use [workflows](https://mastra.ai/docs/workflows/overview) instead.
 
-> **📹 Watch:** Watch [Mastra agent quickstart](https://www.youtube.com/watch?v=G8tXjcseNjg) for a short walkthrough of creating and testing a Mastra agent.
+> **Tip:** Watch an introduction to agents, and how they compare to workflows on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw).
 
 ## Quickstart
 
@@ -151,10 +151,10 @@ export const mastra = new Mastra({
 
 Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features.
 
-Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
-
 > **Tip:** Use [Studio](https://mastra.ai/docs/studio/overview) to test your agent with different messages, inspect tool calls and responses, and debug agent behavior.
 
+> **Note:** Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more information on available properties and configurations.
+
 ## Use your agent
 
 After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/using-tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. Visit the [guides section](https://mastra.ai/guides) to learn how to use agents in your framework of choice.
@@ -205,7 +205,7 @@ Once your agent is running, use this table to find the right page for what you w
 | Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/agents/supervisor-agents)       |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
 | Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/docs/voice/overview)                         |
-| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels/overview)      |
+| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/agents/channels)                     |
 
 ## Multi-agent systems
 

package/.docs/docs/agents/skills.md

@@ -4,7 +4,7 @@
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
 
-You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/overview). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required; use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach — defining skills in code, loading them from files, and resolving them per request.
+You can attach skills directly to an agent without setting up a workspace, filesystem, or sandbox. This is useful when you want portable, code-defined capabilities that travel with your agent definition.
 
 ## When to use agent-level skills
 
@@ -69,7 +69,9 @@ export const releaseChecklist = createSkill({
 })
 ```
 
-The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, like `references/` files in a filesystem skill. Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
+The `references` field bundles supporting documents that the agent can read with the `skill_read` tool, like `references/` files in a filesystem skill.
+
+> **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
 
 ## Filesystem path skills
 
@@ -177,7 +179,7 @@ for (const meta of allSkills) {
 }
 ```
 
-Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.
+> **Note:** Visit [`.getSkill()` reference](https://mastra.ai/reference/agents/getSkill) and [`.listSkills()` reference](https://mastra.ai/reference/agents/listSkills) for the full API.
 
 ## Related
 

package/.docs/docs/agents/structured-output.md

@@ -103,7 +103,7 @@ const response = await testAgent.generate('Help me plan my day.', {
 console.log(response.object)
 ```
 
-Visit [`.generate()`](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
+> **Note:** Visit [`.generate()`](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
 
 **Example output:** The `response.object` will contain the structured data as defined by the schema.
 

package/.docs/docs/agents/supervisor-agents.md

@@ -226,7 +226,9 @@ How it works:
 2. **Scoped memory saves**: Only the delegation prompt and the subagent's response are saved to the subagent's memory
 3. **Fresh thread per invocation**: Each delegation uses a unique thread ID, ensuring clean separation
 
-This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
+This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation.
+
+> **Note:** Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
 
 ## Tool approval propagation
 
@@ -426,5 +428,4 @@ Version overrides propagate automatically through delegation. See [Subagent vers
 - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
 - [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)
-- [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)
-- 📹 [Mastra supervisor agents workshop](https://www.youtube.com/watch?v=FNb2fL9WhQg\&t=1872s)
+- [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)

package/.docs/docs/agents/using-tools.md

@@ -38,7 +38,9 @@ export const weatherTool = createTool({
 })
 ```
 
-When creating tools, keep descriptions concise and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool. Visit the [`createTool`](https://mastra.ai/reference/tools/create-tool) reference for more information on available properties, configurations, and examples.
+When creating tools, keep descriptions concise and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool.
+
+> **Note:** Visit the [`createTool`](https://mastra.ai/reference/tools/create-tool) reference for more information on available properties, configurations, and examples.
 
 To make a tool available to an agent, add it to the `tools` property on the `Agent` class. Mentioning available tools and their general purpose in the agent's system prompt helps the agent decide when to call a tool and when not to.
 
@@ -357,7 +359,7 @@ await agent.generate('Check the forecast', {
 })
 ```
 
-See the [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate) for all runtime options including `toolsets`, `clientTools`, and `prepareStep`.
+> **Note:** See the [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate) for all runtime options including `toolsets`, `clientTools`, and `prepareStep`.
 
 ## Control `toolName` in stream responses
 

package/.docs/docs/browser/agent-browser.md

@@ -99,7 +99,9 @@ const browser = new AgentBrowser({
 })
 ```
 
-This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details. See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
+This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details.
+
+> **Note:** See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
 
 ## Related
 

package/.docs/docs/browser/browser-viewer.md

@@ -140,7 +140,9 @@ npm install -g browse
 browse skills install
 ```
 
-CDP flag: `--ws` See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
+CDP flag: `--ws`
+
+> **Note:** See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
 
 ## Related
 

package/.docs/docs/browser/overview.md

@@ -169,5 +169,4 @@ const browser = new AgentBrowser({
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
-- [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)
-- 📹 [Mastra browser capabilities workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)
+- [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/browser/stagehand.md

@@ -146,7 +146,7 @@ const browser = new StagehandBrowser({
 })
 ```
 
-See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
+> **Note:** See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
 
 ## Recording
 

package/.docs/docs/deployment/mastra-server.md

@@ -14,7 +14,9 @@ Run the build command from your project root:
 mastra build
 ```
 
-This creates a `.mastra` directory containing your production-ready server. Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
+This creates a `.mastra` directory containing your production-ready server.
+
+> **Info:** Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
 
 ## Build output
 
@@ -57,7 +59,7 @@ The `mastra start` command provides additional features:
 - Provides helpful error messages for missing modules
 - Handles process signals for graceful shutdown
 
-Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
+> **Info:** Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
 
 ## Build configuration
 

package/.docs/docs/editor/overview.md

@@ -64,7 +64,9 @@ export const mastra = new Mastra({
 })
 ```
 
-Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
+Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK.
+
+> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
 
 ## Code and database sources
 
@@ -171,7 +173,9 @@ Because stored agents are data, you can build automation loops that tune agents
 - Re-run the experiment against the draft and compare scores to the baseline.
 - Promote the draft to the published version when the scores improve.
 
-This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
+This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested.
+
+> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
 
 ## What can be overridden
 

package/.docs/docs/editor/prompts.md

@@ -122,7 +122,7 @@ await editor.agent.update({
 })
 ```
 
-See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
+> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
 
 ## Versioning
 

package/.docs/docs/editor/tools.md

@@ -52,7 +52,7 @@ Integration providers connect external tool platforms to the editor. Once regist
 
 [Composio](https://composio.dev) gives access to hundreds of integration tools organized into toolkits (GitHub, Slack, Gmail, and others).
 
-1. Get a **project** API key (the `x-api-key` type) from your [Composio dashboard](https://dashboard.composio.dev).
+1. Get an API key from your Composio dashboard.
 
 2. Register the provider in your Editor configuration:
 
@@ -75,7 +75,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    })
    ```
 
-   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. By default, tool calls use the connection pinned by the agent's author. To route calls to each end user's own account instead, see [connection scope](https://mastra.ai/docs/agent-builder/integrations) in the Agent Builder docs.
+   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to the `resourceId` passed through request context for per-user authentication.
 
 ### Arcade
 
@@ -142,7 +142,9 @@ When an agent runs, tools from all sources are merged in this order:
 2. Integration tools
 3. MCP tools
 
-If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description. See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
+If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description.
+
+> **Note:** See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
 
 ## Related
 

package/.docs/docs/evals/custom-scorers.md

@@ -341,7 +341,9 @@ A custom scorer in Mastra uses `createScorer` with four core components:
 3. [**Score Generation**](#score-generation)
 4. [**Reason Generation**](#reason-generation)
 
-Together, these components allow you to define custom evaluation logic using LLMs as judges. Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
+Together, these components allow you to define custom evaluation logic using LLMs as judges.
+
+> **Info:** Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
 
 ```typescript
 import { createScorer } from '@mastra/core/evals'