@mastra/mcp-docs-server 1.2.11 → 1.2.12-alpha.3

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

@@ -14,7 +14,7 @@ import { StagehandBrowser } from '@mastra/stagehand'
 
 const browser = new StagehandBrowser({
   headless: true,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   selfHeal: true,
 })
 
@@ -24,7 +24,7 @@ export const browserAgent = new Agent({
   instructions: `You can browse the web using natural language.
 Use stagehand_act to perform actions like "click the login button".
 Use stagehand_extract to get data from pages.`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   browser,
 })
 ```
@@ -79,7 +79,7 @@ Core tools:
 | ---------------------- | ------------------------------------------------------------------------------------- |
 | `stagehand_act`        | Perform actions using natural language instructions                                   |
 | `stagehand_extract`    | Extract structured data from pages                                                    |
-| `stagehand_observe`    | Discover actionable elements on a page                                                |
+| `stagehand_observe`    | Discover useful elements on a page                                                    |
 | `stagehand_navigate`   | Navigate to a URL                                                                     |
 | `stagehand_tabs`       | Manage browser tabs                                                                   |
 | `stagehand_screenshot` | Capture a screenshot as PNG (viewport by default; set `fullPage: true` for full page) |
@@ -171,7 +171,7 @@ interface ExtractResult<T = unknown> {
 
 ### `stagehand_observe`
 
-Discover actionable elements on a page. Returns a list of elements with their selectors and descriptions.
+Discover useful elements on a page. Returns a list of elements with their selectors and descriptions.
 
 ```text
 // Find specific elements
@@ -222,7 +222,7 @@ Navigate to a URL.
 
 | Parameter   | Type                                            | Description                                     |
 | ----------- | ----------------------------------------------- | ----------------------------------------------- |
-| `url`       | `string`                                        | URL to navigate to (required)                   |
+| `url`       | `string`                                        | URL to open (required)                          |
 | `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | When to consider navigation complete (optional) |
 
 ### `stagehand_tabs`
@@ -245,7 +245,7 @@ Manage browser tabs.
 
 ### `stagehand_screenshot`
 
-Capture a screenshot of the current page as PNG (viewport by default; set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `stagehand_observe` or `stagehand_extract` when you only need text or structured data.
+Capture a screenshot of the current page as PNG (viewport by default. Set `fullPage: true` for full-page capture). Returns image content that vision-capable models can interpret directly. Use `stagehand_observe` or `stagehand_extract` when you only need text or structured data.
 
 ```text
 // Viewport only (default)
@@ -276,7 +276,7 @@ const browser = new StagehandBrowser({
   env: 'BROWSERBASE',
   apiKey: process.env.BROWSERBASE_API_KEY,
   projectId: process.env.BROWSERBASE_PROJECT_ID,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -287,7 +287,7 @@ Configure the AI model for Stagehand operations:
 ```typescript
 // String format: "provider/model"
 const browser = new StagehandBrowser({
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 
 // Object format for custom configuration

package/.docs/reference/channels/slack-provider.md

@@ -6,7 +6,7 @@
 
 ## Usage example
 
-Register the provider on the `Mastra` constructor. The refresh token is single-use and rotates on startup; the resulting access tokens are persisted to `Mastra.storage`.
+Register the provider on the `Mastra` constructor. The refresh token is single-use and rotates on startup. The resulting access tokens are persisted to `Mastra.storage`.
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
@@ -171,7 +171,7 @@ slack.setBaseUrl('https://abc123.trycloudflare.com')
 
 #### `initialize()`
 
-Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Doesn't auto-provision new apps; use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
+Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Doesn't auto-provision new apps. Use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
 
 ```typescript
 await slack.initialize()

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

@@ -60,7 +60,7 @@ yarn dlx create-mastra@latest my-mastra-project --llm anthropic
 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`.
+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 and creates a platform project with the same name as the local project. It then writes `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` to `.env`.
 
 ### Template
 

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

@@ -32,7 +32,7 @@ Comma-separated list of custom arguments to pass to the Node.js process, e.g. `-
 
 #### `--request-context-presets`
 
-Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. When provided, a dropdown displays in Studio's request context editor, letting you quickly switch between preset configurations.
+Path to a JSON file containing [request context](https://mastra.ai/docs/server/request-context) presets. When provided, a dropdown displays in Studio's request context editor, letting you quickly switch between preset configurations.
 
 ```bash
 mastra dev --request-context-presets ./presets.json
@@ -49,7 +49,7 @@ The file must be a JSON object where each key is a preset name and each value is
 
 ### Configs
 
-You can set certain environment variables to modify the behavior of `mastra dev`.
+You can set environment variables to modify the behavior of `mastra dev`.
 
 #### Skip peer dependency check
 
@@ -121,7 +121,7 @@ Under the hood Mastra's Rollup server locates your Mastra entry file and bundles
 
 The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
 
-If you're deploying to a [serverless platform](https://mastra.ai/docs/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform](https://mastra.ai/docs/deployment/cloud-providers) you need to install the correct deployer to receive the correct output in `.mastra`.
 
 It accepts [common flags](#common-flags).
 
@@ -133,7 +133,7 @@ Bundle the Studio UI with the build.
 
 ### Configs
 
-You can set certain environment variables to modify the behavior of `mastra build`.
+You can set environment variables to modify the behavior of `mastra build`.
 
 #### Skip peer dependency check
 
@@ -169,6 +169,55 @@ The path to your built Mastra output directory. Defaults to `.mastra/output`.
 
 Comma-separated list of custom arguments to pass to the Node.js process, e.g. `--require=newrelic` or `--experimental-transform-types`.
 
+## `mastra worker build`
+
+Bundles your Mastra application for worker deployment. Produces the same output as `mastra build` — a self-contained `.mastra/output/` directory.
+
+```bash
+mastra worker build [options]
+```
+
+### Flags
+
+| Flag                  | Description                                                  |
+| --------------------- | ------------------------------------------------------------ |
+| `--dir <path>`        | Path to your Mastra source directory (default: `src/mastra`) |
+| `--root <path>`       | Project root directory (default: current directory)          |
+| `--tools <paths>`     | Comma-separated tool paths to include                        |
+| `--output-dir <path>` | Custom output directory (default: `.mastra/output`)          |
+| `--debug`             | Enable debug logging                                         |
+
+## `mastra worker start`
+
+> **Info:** You need to run `mastra worker build` or `mastra build` before using `mastra worker start`.
+
+Starts a worker process from a previously built bundle.
+
+```bash
+mastra worker start [name] [options]
+```
+
+| Argument/Flag  | Description                                                         |
+| -------------- | ------------------------------------------------------------------- |
+| `name`         | Worker name to start. Sets `MASTRA_WORKERS` in the spawned process. |
+| `--dir <path>` | Path to the build output (default: `.mastra/output`)                |
+| `--env <path>` | Path to environment file (default: `.env.production`, then `.env`)  |
+
+### Examples
+
+```bash
+# Start only the orchestration worker
+mastra worker start orchestration
+
+# Start only the scheduler
+mastra worker start scheduler
+
+# Start from a custom build directory
+mastra worker start orchestration --dir ./dist
+```
+
+See [Workers](https://mastra.ai/docs/deployment/workers) for deployment topologies and configuration.
+
 ## `mastra studio`
 
 Starts [Studio](https://mastra.ai/docs/studio/overview) as a static server. After starting, you can enter your Mastra instance URL (e.g. `http://localhost:4111`) to connect Studio to your Mastra backend. Looks for `.env` and `.env.production` files in the current working directory for configuration.
@@ -199,7 +248,7 @@ The API route prefix of the Mastra API server. Defaults to `/api`.
 
 #### `--request-context-presets`
 
-Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).
+Path to a JSON file containing [request context](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).
 
 ```bash
 mastra studio --request-context-presets ./presets.json
@@ -207,7 +256,7 @@ mastra studio --request-context-presets ./presets.json
 
 ## `mastra deploy`
 
-Builds and deploys your project to a named environment on Mastra platform. This is the recommended command for all new deploys and replaces both [`mastra studio deploy`](#mastra-studio-deploy) and [`mastra server deploy`](#mastra-server-deploy), which continue to work but should no longer be used for new setups.
+Builds and deploys your project to the Mastra platform environment selected by `--env`. This is the recommended command for all new deploys and replaces both [`mastra studio deploy`](#mastra-studio-deploy) and [`mastra server deploy`](#mastra-server-deploy), which continue to work but should no longer be used for new setups.
 
 Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.
 
@@ -217,7 +266,7 @@ mastra deploy --env staging
 mastra deploy --env production --region eu
 ```
 
-The command runs `mastra build`, zips the output, uploads it to the selected environment, and then polls the deploy status while streaming build logs until the deploy reaches a terminal state.
+The command runs `mastra build` and zips the output before uploading it to the selected environment. It then polls the deploy status while streaming build logs until the deploy reaches a terminal state.
 
 Organization, project, and environment are resolved in order from: environment variable (`MASTRA_ORG_ID`, `MASTRA_PROJECT_ID`), CLI flag (`--org`, `--project`, `--env`), `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved org and project IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
 
@@ -294,9 +343,9 @@ mastra deploy --env staging --yes
 
 ## `mastra env`
 
-Manages environments on Mastra platform. Environments are named deploy targets (for example `production`, `staging`, `preview-42`) that belong to a project. The current organization is resolved from stored credentials.
+Manages environments on Mastra platform. Environments are deploy targets (for example `production`, `staging`, `preview-42`) that belong to a project. The current organization is resolved from stored credentials.
 
-Every subcommand resolves its project from, in order: the `MASTRA_PROJECT_ID` environment variable, the `--project <name|slug|id>` flag, or the `.mastra-project.json` file written by [`mastra deploy`](#mastra-deploy) in the current directory. Run from your project directory and you never need to name the project.
+Every subcommand resolves its project in a fixed order. It first checks the `MASTRA_PROJECT_ID` environment variable and the `--project <name|slug|id>` flag. It then reads the `.mastra-project.json` file written by [`mastra deploy`](#mastra-deploy) in the current directory. Run from your project directory and you never need to name the project.
 
 ### `mastra env list`
 
@@ -356,7 +405,7 @@ mastra env restart <env>
 
 ### `mastra env vars pull`
 
-Pulls an environment's env vars into a local env file (default: `.env`). The file contains the merged set a deploy actually runs with: vars stored on the environment (for example, added in the dashboard's environment editor) plus project-level vars, with project values winning on conflict. Managed vars injected by attached databases are listed as comments (names only) since their values are platform-managed secrets.
+Pulls an environment's env vars into a local env file (default: `.env`). The file contains the merged set used by a deploy. It combines vars stored on the environment (for example, added in the dashboard's environment editor) with project-level vars. Project values win on conflict. Managed vars injected by attached databases are listed as comments (names only) since their values are platform-managed secrets.
 
 ```bash
 mastra env vars pull
@@ -373,7 +422,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). 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.
+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.
 
@@ -392,7 +441,7 @@ Emit machine-readable JSON.
 
 ### `mastra env db create`
 
-Provisions a managed database, attaches it, and polls until it's ready. Provisioning errors are printed with the provider's error detail.
+Provisions and attaches a managed database, then polls until it's ready. Provisioning errors are printed with the provider's error detail.
 
 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.
 
@@ -419,7 +468,7 @@ Provider region ID for shared databases. Ignored for environment-scoped database
 
 #### `--shared`
 
-Attach as a project-scoped database that's shared by every environment. Cannot be combined with an environment argument.
+Attach as a project-scoped database that's shared by every environment. Can't be combined with an environment argument.
 
 #### `--no-wait`
 
@@ -475,7 +524,7 @@ Emit machine-readable JSON.
 
 ## `mastra studio deploy`
 
-> **Info:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports named environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
+> **Info:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
 
 Builds and deploys your project to Mastra platform. Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.
 
@@ -483,11 +532,11 @@ Builds and deploys your project to Mastra platform. Requires authentication via
 mastra studio deploy
 ```
 
-The command runs `mastra build`, zips the output, reads an env file from the project directory, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
+The command runs `mastra build` and zips the output. It reads an env file from the project directory before uploading everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.
 
 The deploy command auto-loads the project's `.env` file. If `MASTRA_PROJECT_ID` points to a project that was provisioned for Observability, the deploy links to that project instead of creating a new one. Deploying Studio to an observability-only project converts it into a Studio project on the platform side.
 
-The CLI requires at least one `.env` or `.env.*` file (excluding `.env.example`) in the project directory and fails with `Error: No env file found for deploy.` if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to `.env.production`); pass `--env-file` to choose explicitly. With `--yes` and multiple env files, you must pass `--env-file` or the deploy errors.
+The CLI requires at least one `.env` or `.env.*` file (excluding `.env.example`) in the project directory and fails with `Error: No env file found for deploy.` if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to `.env.production`). Pass `--env-file` to choose explicitly. With `--yes` and multiple env files, you must pass `--env-file` or the deploy errors.
 
 Organization and project are resolved in order from: Environment variable flag, `.mastra-project.json` config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved IDs to `.mastra-project.json` so subsequent deploys skip the prompts.
 
@@ -581,7 +630,7 @@ Shows diagnosis results and suggested fixes for a failed Studio deploy.
 mastra studio deploy suggestions [deploy-id]
 ```
 
-If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. Suggestions appear only when the diagnosis finds a problem.
 
 ### `mastra studio projects`
 
@@ -593,7 +642,7 @@ Creates a new project through an interactive prompt. This command doesn't accept
 
 ## `mastra server deploy`
 
-> **Info:** `mastra server deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which deploys a single project to multiple named environments instead of separate Studio and Server commands. New setups should use `mastra deploy`.
+> **Info:** `mastra server deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which deploys a single project to multiple environments instead of separate Studio and Server commands. New setups should use `mastra deploy`.
 
 Builds and deploys your project to Server on Mastra platform. Works the same as [`mastra studio deploy`](#mastra-studio-deploy) with the same flags, arguments, and resolution logic.
 
@@ -611,7 +660,7 @@ Shows diagnosis results and suggested fixes for a failed Server deploy.
 mastra server deploy suggestions [deploy-id]
 ```
 
-If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.
+If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. Suggestions appear only when the diagnosis finds a problem.
 
 ## `mastra server pause`
 
@@ -649,7 +698,7 @@ Same flags as [`mastra server pause`](#mastra-server-pause): **`--org`**, **`--p
 mastra server restart
 ```
 
-Fails if a deployment is still active for this project (running, building, deploying, etc.); that's a platform restriction so you can't restart while another deploy is in progress.
+Fails if a deployment is still active for this project (running, building, deploying, etc.). That's a platform restriction so you can't restart while another deploy is in progress.
 
 ## `mastra server env`
 
@@ -892,7 +941,7 @@ Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "c
 
 #### `--observability`
 
-Enable Observability on the Mastra platform. The CLI prompts you to select an existing platform project or create a new one, writes the required environment variables, and configures the observability exporters.
+Enable Observability on the Mastra platform. The CLI prompts you to select an existing platform project or create a new one. It then writes the required environment variables and configures the observability exporters.
 
 #### `--no-observability`
 
@@ -906,7 +955,7 @@ Set the platform project name to use when Mastra Observability is enabled.
 
 Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.
 
-The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
+The command bundles your project and connects to your configured storage backend. It then executes any pending migrations. Currently supports:
 
 - **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
 - **ClickHouse legacy-to-vNext span migration**: Copies historical spans from the legacy `mastra_ai_spans` table to the vNext `mastra_span_events` schema. Runs in batches to stay within memory limits. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
@@ -968,13 +1017,15 @@ For runtime commands, the command resolves the target server in this order:
 
 Automatic platform auth is only used when the CLI resolves a Mastra platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
-For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. It resolves credentials in this order:
+For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. Trace Intelligence commands (`learning`) work the same way but target `https://output.signals.mastra.ai`. Both resolve credentials in this order:
 
 1. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
 2. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your environment.
 3. Project metadata from `.mastra-project.json` for the project ID.
 4. Your Mastra CLI login token as an auth fallback.
 
+Learning commands also send `X-Mastra-Organization-Id`, resolved from an explicit `--header`, `MASTRA_ORGANIZATION_ID` in your environment, or `.mastra-project.json`, in that order.
+
 Use `--url` and `--header` when you need to override the default hosted observability target or credentials.
 
 ### Flags
@@ -1417,7 +1468,7 @@ curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/sp
 
 #### `mastra api score create`
 
-Creates an observability score. The input uses the server score body shape; inspect it with `--schema`.
+Creates an observability score. The input uses the server score body shape. Inspect it with `--schema`.
 
 ```bash
 mastra api score create <input>
@@ -1503,6 +1554,86 @@ Lists results for an experiment. Pass optional JSON input for route-supported fi
 mastra api experiment results <datasetId> <experimentId> [input]
 ```
 
+#### `mastra api learning entities`
+
+Lists entities (agents) with Trace Intelligence output, including which trace signals are available per entity. Requires enrollment in the Trace Intelligence private beta.
+
+```bash
+mastra api learning entities '{"entityType":"agent"}'
+```
+
+#### `mastra api learning snapshots`
+
+Lists analysis snapshots for an entity and an ordered, comma-separated list of trace signals. Later commands need a `snapshotId` from this list.
+
+```bash
+mastra api learning snapshots <entityId> '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}'
+```
+
+#### `mastra api learning flow`
+
+Gets the cross-signal theme flow for one snapshot: stages and links for a Sankey-style view where counts are distinct traces.
+
+```bash
+mastra api learning flow <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>"}'
+```
+
+#### `mastra api learning paths`
+
+Gets per-trace theme assignments across the ordered trace signals in one snapshot. Paginate with `limit` and `offset`.
+
+```bash
+mastra api learning paths <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>","limit":100}'
+```
+
+#### `mastra api learning theme list`
+
+Lists themes for one trace signal in one snapshot.
+
+```bash
+mastra api learning theme list <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
+```
+
+#### `mastra api learning theme get`
+
+Gets one theme in one snapshot by its numeric theme ID.
+
+```bash
+mastra api learning theme get <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
+```
+
+#### `mastra api learning theme examples`
+
+Lists trace examples for one theme in one snapshot. Paginate with `limit` and `offset`.
+
+```bash
+mastra api learning theme examples <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
+```
+
+#### `mastra api learning theme history`
+
+Gets the lifecycle history for one durable theme across snapshots, including split and merge relationships. Takes no `snapshotId`.
+
+```bash
+mastra api learning theme history <entityId> <themeId> '{"entityType":"agent","signalName":"goal"}'
+```
+
+#### `mastra api learning noise get`
+
+Gets the unclustered (noise) bucket for one trace signal in one snapshot.
+
+```bash
+mastra api learning noise get <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
+```
+
+#### `mastra api learning noise examples`
+
+Lists trace examples for the noise bucket in one snapshot. Paginate with `limit` and `offset`.
+
+```bash
+mastra api learning noise examples <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
+```
+
 ## Common flags
 
 ### `--dir`

package/.docs/reference/client-js/agents.md

@@ -2,7 +2,7 @@
 
 # Agents API
 
-The Agents API provides methods to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools.
+The Agents API provides methods to interact with Mastra AI agents, including generating responses and streaming interactions. It also provides methods for managing agent tools.
 
 ## Getting all agents
 
@@ -155,7 +155,7 @@ for await (const part of uiMessageStream) {
 
 ### `sendMessage()`
 
-Send user-authored input to an active agent run or idle memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives, the message.
+Send user-authored input to an active agent run or idle memory thread. Use this with `subscribeToThread()` so the client can render the stream that wakes from, or receives the message.
 
 ```typescript
 const agent = mastraClient.getAgent('support-agent')
@@ -285,7 +285,7 @@ await subscription.processDataStream({
 
 ### `streamUntilIdle()`
 
-Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
+Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `stream()`.
 
 ```typescript
 const response = await agent.streamUntilIdle('Research solana for me', {
@@ -307,7 +307,7 @@ response.processDataStream({
 
 ### `resumeStreamUntilIdle()`
 
-Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `resumeStream()`:
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `resumeStream()`:
 
 ```typescript
 const response = await agent.resumeStreamUntilIdle(
@@ -366,7 +366,7 @@ response.processDataStream({
 
 ### `listSuspendedRuns()`
 
-List suspended runs for the agent from storage — runs waiting on a tool-call approval or on a tool that suspended. Discovery is backed by storage, so it works after a server restart and across server instances. Pass the returned `runId` to `approveToolCall()`, `declineToolCall()`, or `resumeStream()`.
+List suspended runs for the agent from storage: runs waiting on a tool-call approval or on a tool that suspended. Discovery is backed by storage, so it works after a server restart and across server instances. Pass the returned `runId` to `approveToolCall()`, `declineToolCall()`, or `resumeStream()`.
 
 ```typescript
 const { runs, total } = await agent.listSuspendedRuns({
@@ -655,9 +655,9 @@ const screenshotTool = createTool({
 
 ### Tracing client tools
 
-When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call, injects a W3C trace carrier into the outgoing tool-call chunk, and ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.
+When `@mastra/observability` is installed and configured on the server, a client-side tool records a `CLIENT_TOOL_CALL` span as a child of the current `AGENT_RUN` span. The server creates that span when the model emits the client tool call and injects a W3C trace carrier into the outgoing tool-call chunk. It ends the span once the tool arguments are available. Without server-side observability configured, client tool tracing is a no-op.
 
-The client SDK also measures the wall-clock duration of each client tool's `execute` function and ships it back to the server, where it's emitted as a `mastra_tool_duration_ms` metric with `toolType: "client"`.
+The client SDK also measures the wall-clock duration of each client tool's `execute` function and sends it back to the server, where it's emitted as a `mastra_tool_duration_ms` metric with `toolType: "client"`.
 
 For richer telemetry from inside your tool's `execute` function, use the `observe` helper on the execution context to add child spans and structured logs:
 
@@ -680,9 +680,9 @@ const fetchUserTool = createTool({
 })
 ```
 
-`observe` is always available — when no tracing context is active (e.g. running outside a traced agent), `span` runs the function directly and `log` is a no-op. No null-checking needed.
+`observe` is always available: when no tracing context is active (e.g. running outside a traced agent), `span` runs the function directly and `log` is a no-op. No null-checking needed.
 
-The SDK serializes everything the collector buffered as OTLP/JSON and ships it back in the next request body. The server's `@mastra/observability` package validates that the spans belong to the correct trace (preventing cross-trace injection) and forwards each span/log into the same observability bus that server-side telemetry uses. Your existing exporters pick them up automatically after observability is configured.
+The SDK serializes everything the collector buffered as OTLP/JSON and sends it back in the next request body. The server's `@mastra/observability` package validates that the spans belong to the correct trace (preventing cross-trace injection) and forwards each span/log into the same observability bus that server-side telemetry uses. Your existing exporters pick them up automatically after observability is configured.
 
 ## Stored agents
 
@@ -727,6 +727,23 @@ const agent = await mastraClient.createStoredAgent({
 })
 ```
 
+By default, `createStoredAgent()` publishes the initial version immediately. Set `autoPublish` to `false` to create an unpublished draft that you can review before calling [`activateVersion()`](#activateversion):
+
+```typescript
+const draft = await mastraClient.createStoredAgent({
+  id: 'draft-agent',
+  name: 'Draft Assistant',
+  instructions: 'You are a helpful assistant.',
+  model: {
+    provider: 'openai',
+    name: 'gpt-5',
+  },
+  autoPublish: false,
+})
+```
+
+Editors configured with the `code` source always publish the initial version because saving writes the agent configuration to the file system.
+
 With all options:
 
 ```typescript

package/.docs/reference/client-js/memory.md

@@ -168,7 +168,7 @@ const result = await thread.listMessages({
 })
 ```
 
-Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. Every key-value pair must match with AND semantics. `null` matches an explicit `null` value, not a missing metadata key. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the server storage backend, and arbitrary metadata filters may scan candidate messages.
+Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. Every key-value pair must match with AND semantics. `null` matches only keys explicitly set to `null`. Metadata keys must start with a letter or underscore and contain only alphanumeric or underscore characters. The limit is 128 characters. Reserved prototype keys such as `__proto__`, `constructor`, and `prototype` aren't allowed. Performance depends on the server storage backend, and arbitrary metadata filters may scan candidate messages.
 
 ### Delete Messages
 
@@ -226,7 +226,7 @@ await mastraClient.updateWorkingMemory({
 // Returns: { success: true }
 ```
 
-**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+For resource-scoped working memory, you must provide the `resourceId` parameter. It allows the memory to persist across all conversation threads for that user.
 
 ### Get Memory Status
 

package/.docs/reference/client-js/workflows.md

@@ -142,7 +142,7 @@ await run.resume({
 })
 ```
 
-When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based; `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
+When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based. `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
 
 ```typescript
 await run.resume({

package/.docs/reference/coding-agent/build-base-prompt.md

@@ -2,11 +2,11 @@
 
 # buildBasePrompt()
 
-`buildBasePrompt()` builds the shared base system prompt for a coding agent — the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
+`buildBasePrompt()` builds the shared base system prompt for a coding agent: the behavioral instructions that make the agent a good coding assistant. It takes a `PromptContext` describing the current environment (project, platform, git branch, mode, model) and returns the prompt as a string.
 
 Product-specific strings are parameterized through `productName`, `coAuthorName`, and `coAuthorEmail`, so you can rebrand the prompt and commit trailer without forking it. They default to `"Mastra Code"` / `"noreply@mastra.ai"`, so existing callers keep identical output.
 
-Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build dynamic instructions for the agent.
+Use this with [`createCodingAgent()`](https://mastra.ai/reference/coding-agent/create-coding-agent) when you build runtime-defined instructions for the agent.
 
 ## Usage example
 

package/.docs/reference/coding-agent/create-coding-agent.md

@@ -4,7 +4,7 @@
 
 `createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only `model`, `instructions`, and `tools` to get a working agent, or override any default.
 
-The returned value is a standard `Agent`, so it works anywhere an `Agent` does — including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+The returned value is a standard `Agent`, so it works anywhere an `Agent` does: including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 ## Usage example
 
@@ -70,7 +70,7 @@ new Workspace({
 })
 ```
 
-To opt out — for example when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level — pass `workspace: undefined` explicitly:
+To opt out (for example, when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level), pass `workspace: undefined` explicitly:
 
 ```typescript
 const agent = createCodingAgent({