@mastra/mcp-docs-server 1.2.27-alpha.1 → 1.2.27-alpha.11

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

@@ -168,6 +168,190 @@ The CLI can infer platform credentials from your project environment. See the [`
 
 You can query exported feedback over HTTP. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, and project scoping.
 
+## Import existing traces
+
+Use `mastra traces import` to move existing trace history from a supported observability provider into an existing Mastra Platform project. The command reads and validates complete traces at the source, converts them into Mastra spans, then uses a shared workflow for preparation, upload, resume, and verification.
+
+The import command currently supports Langfuse. Additional providers can use the same command workflow when their adapters are added.
+
+| Provider | Command argument | Source requirement                                 |
+| -------- | ---------------- | -------------------------------------------------- |
+| Langfuse | `langfuse`       | Langfuse Cloud or self-hosted Langfuse v4 or later |
+
+### Prerequisites
+
+Before starting an import, you need:
+
+- A Mastra Platform project.
+- Mastra Platform authentication through `mastra auth login`, or a `MASTRA_API_TOKEN` and `MASTRA_ORG_ID` for a headless environment.
+- `MASTRA_PLATFORM_ACCESS_TOKEN` for upload and read-back when using an interactive login. A dry run doesn't require this token.
+- Credentials for a supported source provider.
+- Enough local disk space to temporarily store the prepared traces.
+
+### Configure the destination
+
+For an interactive import, sign in and select the organization that owns the destination project:
+
+```bash
+npx mastra auth login
+npx mastra auth orgs switch
+```
+
+Interactive login authorizes project discovery. Set the Platform access token used by the destination project before uploading or verifying traces:
+
+```bash
+MASTRA_PLATFORM_ACCESS_TOKEN=<mastra-platform-access-token>
+```
+
+If `mastra init` configured observability for the project, use the token it wrote to `.env`. Otherwise, create an access token in [Mastra Platform](https://projects.mastra.ai).
+
+You can run `--dry-run` without this token because a dry run doesn't contact the collector or query API.
+
+Specify the destination with `--project`, or set `MASTRA_PROJECT_ID`. You can use a project name, slug, or ID with `--project`:
+
+```bash
+npx mastra traces import langfuse --project my-project --dry-run
+```
+
+If `MASTRA_PROJECT_ID` is set, it takes precedence over `--project`. Without either value, the CLI uses the project linked in `.mastra-project.json`.
+
+For a headless environment, set the API token and organization ID. The command uses `MASTRA_API_TOKEN` for project discovery, upload, and read-back. Set the project ID or pass `--project`:
+
+```bash
+MASTRA_API_TOKEN=<mastra-api-token>
+MASTRA_ORG_ID=<organization-id>
+MASTRA_PROJECT_ID=<project-id>
+```
+
+### Configure Langfuse
+
+Create [project API keys in Langfuse](https://langfuse.com/docs/api-and-data-platform/features/public-api), then add them to `.env` or `.env.local` in the directory where you run the command:
+
+```bash
+LANGFUSE_PUBLIC_KEY=<langfuse-public-key>
+LANGFUSE_SECRET_KEY=<langfuse-secret-key>
+```
+
+Langfuse Cloud defaults to the EU region at `https://cloud.langfuse.com`. Set `LANGFUSE_BASE_URL` to the [regional host](https://langfuse.com/security/data-regions) for US, Japan, or HIPAA Cloud, or to the origin of a self-hosted instance:
+
+```bash
+LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
+```
+
+### Preview the import
+
+Run a dry run before uploading:
+
+```bash
+npx mastra traces import langfuse --project my-project --dry-run
+```
+
+The dry run reads the source, prepares valid Mastra traces locally, and reports:
+
+- The source and destination projects.
+- The fixed import window.
+- Prepared and skipped trace and span counts.
+- The size of the prepared local data.
+- Provider warnings and skip reasons in `report.json`.
+
+It doesn't upload traces. The command prints a `--resume` command that uploads the prepared data later without reading the source again.
+
+### Choose the import window
+
+By default, the command selects the last 30 days, ending when the import starts. Use `--from` and `--to` to choose a smaller window:
+
+```bash
+npx mastra traces import langfuse \
+  --project my-project \
+  --from "$FROM" \
+  --to "$TO" \
+  --dry-run
+```
+
+Set `FROM` and `TO` to ISO 8601 dates or timestamps. The following rules apply:
+
+- `--to` can't be in the future or outside the current 30-day Platform retention period.
+- `--from` must be earlier than `--to` and inside the current retention period.
+- The selected window can't exceed 30 days.
+- If only `--to` is set, the default start is the later of 30 days before `--to` and the current retention boundary.
+
+Trace eligibility is based on the root observation's start time. The Langfuse adapter discovers roots in the selected window and then reads all currently available observations for each selected trace. It skips the complete trace if the available parent-child tree or timestamps are invalid.
+
+### Upload and verify
+
+Run the command without `--dry-run` to upload the prepared traces:
+
+```bash
+npx mastra traces import langfuse --project my-project
+```
+
+The CLI displays the preparation summary and asks for confirmation before upload. Pass `--yes` to skip this prompt in an automated environment:
+
+```bash
+npx mastra traces import langfuse --project my-project --yes
+```
+
+The importer keeps every trace in one upload request and checkpoints progress only after Mastra Platform acknowledges the batch. Temporary source and destination failures use bounded retries.
+
+After every prepared trace is acknowledged, the importer reads back a deterministic sample of up to 10 traces. It verifies span IDs, parent links, names, span types, event flags, timestamps, and whether an error is present. It doesn't read back or compare input, output, attributes, metadata, or tags.
+
+If read-back isn't available yet or a sampled trace differs, the import pauses and keeps its prepared data. Resume the import to retry verification without uploading acknowledged traces again.
+
+### Resume an import
+
+Use the exact command printed by the CLI when a dry run, cancellation, interruption, upload failure, or paused verification leaves an import unfinished:
+
+```bash
+npx mastra traces import langfuse \
+  --resume 00000000-0000-0000-0000-000000000000 \
+  --project my-project
+```
+
+A resumed import must use the original provider and destination project. Its saved date window can't be changed, so `--from`, `--to`, and `--dry-run` can't be combined with `--resume`.
+
+Resume behavior depends on where the command stopped:
+
+- An interrupted preparation reads and prepares the source again.
+- An interrupted upload starts with the first unacknowledged trace.
+- Paused verification retries read-back without re-uploading acknowledged traces.
+- A completed import reports that it's already complete and retries any remaining local cleanup.
+
+### Local files and cleanup
+
+Import state is stored under:
+
+```text
+~/.mastra/imports/traces/<target-project-id>/<import-id>/
+```
+
+| File            | Purpose                                                                     | Lifecycle                                                                                 |
+| --------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `manifest.json` | Stores the source identity, date window, counts, and acknowledged progress. | Retained after completion.                                                                |
+| `traces.jsonl`  | Stores one complete normalized trace per line.                              | Retained for dry runs and unfinished imports, then removed after successful verification. |
+| `report.json`   | Stores counts, warnings, skip samples, and verification results.            | Retained after it's written.                                                              |
+
+These files can contain trace content. Mastra creates the import directory and files with permissions restricted to the local user. Protect the machine and account that run the import.
+
+### Imported data and limits
+
+For Langfuse imports:
+
+- Observations become Mastra spans with their parent-child relationships and timestamps.
+- Supported fields such as names, input, output, errors, model details, usage, cost, tags, and source context are mapped when present.
+- Destination trace and span IDs are deterministic. Original Langfuse IDs remain in span metadata for correlation.
+- Unknown Langfuse observation types become generic spans and produce a warning instead of being silently discarded.
+- Only trace observations are imported. Scores, feedback, datasets, attachments, and logs aren't imported.
+
+The shared importer also applies these limits:
+
+- Prepared local trace data is limited to 5 GiB per import. Use a smaller date window if an import reaches this limit.
+- A complete trace must fit within the importer's 4 MiB upload payload limit. A larger trace is skipped and recorded with the `trace_too_large` reason.
+- A trace is never split between upload requests.
+
+Review `report.json` after a dry run or completed import to see exactly what was prepared, skipped, acknowledged, and verified.
+
+See the [`mastra traces import` CLI reference](https://mastra.ai/reference/cli/mastra) for the complete option and environment-variable reference.
+
 ## Next steps
 
 - 📹 [Mastra observability and Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)

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

@@ -14,6 +14,8 @@ Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-pl
 
 Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`) and provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data. Each environment also gets a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspaces) that gives agents a filesystem and sandbox with no manual configuration.
 
+Organization-level [**Alerts**](https://mastra.ai/docs/mastra-platform/alerts) notify your team when deploys fail or running services stop. Alerts can cover every project or selected projects and environments, with notifications sent to Slack, email, or webhooks.
+
 [**Trace Intelligence**](https://mastra.ai/docs/mastra-platform/trace-intelligence) finds recurring goals, outcomes, behaviors, and sentiment across your agent traces. Trace Intelligence is available in private beta for selected projects.
 
 ## Get started

package/.docs/docs/memory/message-history.md

@@ -124,6 +124,27 @@ You can use this history in two ways:
 
 > **Note:** `lastMessages` counts every stored message, including tool calls, tool results, and [signals](https://mastra.ai/docs/harness/signals) of any kind, so a single turn can add several messages to the count. The window also slides forward on every request: once a thread grows past the limit, the oldest message leaves context on each turn, which changes the start of the prompt and invalidates the provider prompt cache. For long-running conversations, use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps the prompt prefix stable.
 
+### Limit history by tokens
+
+Message count is a poor proxy for context size: a tool result can be a few tokens or thousands. Use `messageHistory` to keep recent history within a token budget instead:
+
+```typescript
+export const agent = new Agent({
+  id: 'test-agent',
+  memory: new Memory({
+    options: {
+      messageHistory: { maxTokens: 8_000, atMaxRemoveTokens: 2_000 },
+    },
+  }),
+})
+```
+
+Mastra counts the complete prompt against `maxTokens`, including remembered history, system instructions, context, and the current turn. When the prompt exceeds the budget, Mastra removes the oldest remembered messages until the prompt is at most `maxTokens - atMaxRemoveTokens`. `atMaxRemoveTokens` defaults to 25% of `maxTokens`. Removing history in chunks keeps the prompt prefix stable across several turns, which helps provider prompt caches stay warm.
+
+System messages, context, the current turn's input, and the agent's responses are never trimmed. Linked tool calls and results are removed together. If protected content alone exceeds `maxTokens`, Mastra removes all remembered history but keeps the protected content.
+
+Trimmed messages stay in storage. During agent runs, Mastra persists a per-thread boundary so they're excluded from later turns. Setting `messageHistory` without `lastMessages` disables the default 10-message cap. Set both to combine a count cap with a token budget. Set `maxTokens` to `0` to disable message history.
+
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
 ## Thread title generation

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

@@ -849,6 +849,39 @@ Transform hooks are always awaited, on every path (manual `observe()`/`reflect()
 
 Because hooks receive `threadId` and `resourceId`, you can also use them to update [working memory](https://mastra.ai/docs/memory/working-memory) via `memory.updateWorkingMemory()` during a cycle. These external updates aren't atomic with the OM text commit.
 
+### Redact skill results
+
+Agent skills are injected into the agent as tools (`skill`, `skill_search`, `skill_read`). Their results contain the skill's full instructions or file contents, so without redaction the Observer re-observes that text every time a skill is used. `skillResultRedactor()` is a ready-made `beforeObservation` hook that replaces those results with a placeholder and leaves everything else in place. The tool call survives, so the Observer still records which skill was used and what it was called with.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { skillResultRedactor } from '@mastra/memory/hooks'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      hooks: {
+        beforeObservation: skillResultRedactor(),
+      },
+    },
+  },
+})
+```
+
+Pass `toolNames` to redact results from a different set of tools. Because a hook is a function over the messages, it composes with your own transforms by chaining the outputs. Await each chained hook so an async one isn't discarded:
+
+```typescript
+const dropSkillResults = skillResultRedactor()
+
+hooks: {
+  beforeObservation: async input => {
+    const messages = (await dropSkillResults(input))?.messages ?? input.messages
+    return { messages: messages.filter(m => m.role !== 'signal') }
+  },
+}
+```
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.

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

@@ -130,7 +130,7 @@ await observability!.deleteFeedback({
 })
 ```
 
-Deleted records also disappear from feedback analytics. ClickHouse uses a lightweight delete to hide rows without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. ClickHouse doesn't configure a retention TTL for deletion requests in open-source deployments. Delete APIs intentionally leave cursor-only delta rows untouched. These rows contain identifiers rather than feedback payloads and expire within two days.
+Deleted records also disappear from feedback analytics. ClickHouse uses a lightweight delete to hide rows without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. Configure retention for every observability signal to expire deletion requests after the signal rows they protect. If any signal is unbounded, deletion requests also remain unbounded to prevent deleted data from being reintroduced. Delete APIs intentionally leave cursor-only delta rows untouched. These rows contain identifiers rather than feedback payloads and expire within two days.
 
 ## Query feedback analytics
 

package/.docs/docs/observability/tracing/overview.md

@@ -459,6 +459,8 @@ export const mastra = new Mastra({
 })
 ```
 
+`process()` must mutate the span it receives and return the same instance, or return `undefined` to drop the span. Don't return a copy (for example `{ ...span, input: '...' }`): `exportSpan()` and `isValid` are instance members of the live span, so a copy can't be exported. Mastra logs a processor error and drops the span in that case.
+
 Processors are executed in the order they're defined, allowing you to chain multiple transformations. Common use cases include:
 
 - Redacting sensitive data (passwords, tokens, API keys)

package/.docs/docs/server/custom-adapters.md

@@ -371,6 +371,49 @@ await server.init()
 app.listen(4111)
 ```
 
+## Test adapter compatibility
+
+Use `@mastra/server-adapters-test-suite` to run the same conformance tests as Mastra's official adapters. Install it with its peer dependencies in your adapter project:
+
+**npm**:
+
+```bash
+npm install --save-dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+**pnpm**:
+
+```bash
+pnpm add --save-dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+**Yarn**:
+
+```bash
+yarn add --dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+**Bun**:
+
+```bash
+bun add --dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+Provide framework-specific setup and request execution functions to the route suite:
+
+```typescript
+import { createRouteAdapterTestSuite } from '@mastra/server-adapters-test-suite'
+import { executeHttpRequest, setupAdapter } from './adapter-test-helpers'
+
+createRouteAdapterTestSuite({
+  suiteName: 'My framework adapter',
+  setupAdapter,
+  executeHttpRequest,
+})
+```
+
+The package also provides root exports for Model Context Protocol (MCP), multipart request, HTTP logging, and body limit tests. See the [package README](https://github.com/mastra-ai/mastra/tree/main/server-adapters/server-adapters-test-suite) for the supported peer dependency versions.
+
 > **Tip:** The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server-adapters/hono/src/index.ts) and [@mastra/express](https://github.com/mastra-ai/mastra/blob/main/server-adapters/express/src/index.ts) implementations are good references when building your custom adapter. They show how to handle framework-specific patterns for context storage and middleware registration, plus response handling.
 >
 > If you want to use [Studio](https://mastra.ai/docs/studio/overview) with your server adapter, use [`mastra studio`](https://mastra.ai/reference/cli/mastra) to only launch the Studio UI.

package/.docs/docs/subagents.md

@@ -135,11 +135,13 @@ The subagent reads these entries in its tools and dynamic configuration, such as
 Called after a delegation finishes. Use it to inspect results or provide feedback, or alternatively stop execution:
 
 - `context.bail()`: Stop the parent agent's loop immediately
-- Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is available on the next turn
 - Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
 
 Set `resultText` when the subagent's own result would give the parent a misleading signal. For example, empty text from a subagent stopped on a tool-calls step looks like a successful but empty delegation to the parent model. You can also replace the error text from a failed delegation with a more useful message. This doesn't recover the delegation. The parent still receives a failed tool result. Unlike `feedback` on the next turn, `resultText` affects the parent's reasoning immediately.
 
+To stop the parent agent on failure and save feedback for a later turn, call `bail()` and return `feedback`:
+
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
   maxSteps: 10,
@@ -161,12 +163,41 @@ const stream = await parentAgent.stream('Research AI trends', {
 
 The `context` object includes:
 
-| Property      | Description                                                                                   |
-| ------------- | --------------------------------------------------------------------------------------------- |
-| `primitiveId` | The ID of the subagent that ran                                                               |
-| `result`      | The subagent's response, including `text`, `usage`, `finishReason`, and `subAgentToolResults` |
-| `error`       | Error if the delegation failed                                                                |
-| `bail()`      | Function to stop the parent agent's loop                                                      |
+| Property      | Description                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `primitiveId` | The ID of the subagent that ran                                                                                                                        |
+| `result`      | The subagent's response, including `text`, `usage`, `finishReason`, `subAgentToolResults`, `subAgentThreadId`, and `subAgentResourceId` when available |
+| `success`     | Whether the delegation succeeded                                                                                                                       |
+| `error`       | The original error if the delegation failed                                                                                                            |
+| `messages`    | The collected subagent transcript, including partial messages when available                                                                           |
+| `bail()`      | Function to stop the parent agent's loop                                                                                                               |
+
+#### Failed delegations
+
+When a subagent run fails, the parent model receives a failed tool result with a generic error message. This doesn't automatically stop the parent agent, which can explain the failure or choose another approach. Call `context.bail()` to stop its loop instead.
+
+The hook receives `success: false`, the original `error`, and any collected partial results and messages. Returning `resultText` replaces the error text the parent model sees without changing the delegation's failed status or discarding its original cause. An empty string is also a valid replacement.
+
+To let the parent continue with a curated failure message instead of stopping its loop, return `resultText` without calling `bail()`:
+
+```typescript
+const stream = await parentAgent.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    onDelegationComplete: ({ success }) => {
+      if (!success) {
+        return {
+          resultText: 'The delegated task failed. Try another approach.',
+        }
+      }
+    },
+  },
+})
+```
+
+Prefer a curated message, as in this example. Returning `{ resultText: error.message }` explicitly forwards the underlying message to the parent model's provider, and the model may repeat it to the end user. Provider errors can contain sensitive information. A generic `resultText` isn't a redaction policy for logs, traces, or streamed error payloads.
+
+For delegations run as [background tasks](https://mastra.ai/docs/harness/background-tasks), configured retries can invoke `onDelegationComplete` once per attempt. Account for repeated calls if your hook has side effects.
 
 ### Hook errors
 

package/.docs/integrations/channels/github.md

@@ -41,9 +41,13 @@ GitHub Signals requires:
 - A Mastra storage adapter with memory and notification support. The provider stores each subscription in the thread's metadata, so the thread must already exist.
 - The `gitcrawl` command on `PATH`, configured to access the repositories you want to monitor. The provider runs `gitcrawl sync` and reads its SQLite database.
 - The `sqlite3` command on `PATH`.
-- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses `gh api` to check whether comment authors have access to the repository before notifying the agent.
+- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses real `gh api` responses to check repository permissions and GitHub App ownership before notifying the agent.
 
-By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are also allowed. Configure `authorizedPermissions`, `authorizedBots`, or `ignoredBots` when you need different rules.
+By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are explicitly allowed.
+
+Bot authorization checks `ignoredBots` first, using an exact case-insensitive login match. Other bots can trigger notifications when they appear in `authorizedBots`, when the GitHub App is owned by a user whose repository permission appears in `authorizedPermissions`, or when the app is owned by the organization that owns the repository. The default authorized permissions are `admin`, `maintain`, and `write`.
+
+Failed, inaccessible, malformed, and unsupported app-owner lookups deny the bot comment. Successful app-owner lookups are cached for 24 hours; failed lookups aren't cached.
 
 ## Agent and subscription
 

package/.docs/integrations/databases/clickhouse.md

@@ -91,7 +91,7 @@ Trace deletion cascades to spans, trace roots and branches, metrics, logs, score
 
 Lightweight deletion is a hide-only operation that marks rows with ClickHouse's `_row_exists` mask. Physical removal depends on merges and deployment-configured retention TTLs. `ObservabilityStorageClickhouseVNext` applies retention only when you provide a `RetentionConfig`; Mastra OSS doesn't configure a default retention TTL.
 
-Deletion requests aren't purged automatically in Mastra OSS. Automatic retirement will be introduced with future database-agnostic retention configuration.
+When all five observability signals have finite retention, Mastra also applies a TTL to deletion requests so they outlive the signal rows they protect. If any signal is unbounded, deletion requests remain unbounded. See [storage retention](https://mastra.ai/reference/storage/retention) for how the deletion-request TTL is calculated.
 
 ### Observability with the legacy domain
 

package/.docs/integrations/observability/confident-ai.md

@@ -4,49 +4,49 @@
 
 # Confident AI
 
-[Confident AI](https://www.confident-ai.com/) is an LLM observability and evaluation platform for teams to build reliable AI applications in both development and production.
+[Confident AI](https://www.confident-ai.com/) is an LLM observability and evaluation platform for teams building reliable AI applications in both development and production.
 
-The `@mastra/deepeval` package sends your Mastra traces to Confident AI, where you can run metrics against them and track quality over time. It builds on [DeepEval](https://www.confident-ai.com/docs), the open-source evaluation SDK behind the platform.
+The `ConfidentMastraExporter` from [`confident-trace`](https://github.com/confident-ai/confident-trace) sends your Mastra traces to Confident AI, where agent runs show up with the full agent, model, and tool hierarchy, and can be scored automatically as they arrive.
 
 ## Installation
 
 **npm**:
 
 ```bash
-npm install @mastra/deepeval@latest
+npm install confident-trace@latest
 ```
 
 **pnpm**:
 
 ```bash
-pnpm add @mastra/deepeval@latest
+pnpm add confident-trace@latest
 ```
 
 **Yarn**:
 
 ```bash
-yarn add @mastra/deepeval@latest
+yarn add confident-trace@latest
 ```
 
 **Bun**:
 
 ```bash
-bun add @mastra/deepeval@latest
+bun add confident-trace@latest
 ```
 
 ## Configuration
 
 ### Prerequisites
 
-1. **Confident AI account**: Sign up at [confident-ai.com](https://www.confident-ai.com/)
+1. **Confident AI account**: Sign up at [confident-ai.com](https://app.confident-ai.com)
 2. **API key**: Generate one in your Confident AI project settings
 3. **Environment variables**: Set your credentials:
 
 ```bash
 CONFIDENT_API_KEY=confident_proj_xxxxxxxxxxxxx
 
-# Optional
-CONFIDENT_TRACE_ENVIRONMENT=production  # Defaults to "development"
+# Optional. EU region, defaults to the US servers
+CONFIDENT_OTEL_ENDPOINT=https://eu.otel.confident-ai.com/v1/traces
 ```
 
 ### Zero-Config Setup
@@ -56,14 +56,14 @@ With environment variables set, use the exporter with no configuration:
 ```typescript
 import { Mastra } from '@mastra/core'
 import { Observability } from '@mastra/observability'
-import { DeepEvalExporter } from '@mastra/deepeval'
+import { ConfidentMastraExporter } from 'confident-trace/mastra'
 
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
-      deepeval: {
+      confidentAI: {
         serviceName: 'my-service',
-        exporters: [new DeepEvalExporter()],
+        exporters: [new ConfidentMastraExporter()],
       },
     },
   }),
@@ -77,17 +77,17 @@ You can also pass credentials directly (takes precedence over environment variab
 ```typescript
 import { Mastra } from '@mastra/core'
 import { Observability } from '@mastra/observability'
-import { DeepEvalExporter } from '@mastra/deepeval'
+import { ConfidentMastraExporter } from 'confident-trace/mastra'
 
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
-      deepeval: {
+      confidentAI: {
         serviceName: 'my-service',
         exporters: [
-          new DeepEvalExporter({
+          new ConfidentMastraExporter({
             apiKey: process.env.CONFIDENT_API_KEY,
-            environment: 'production',
+            endpoint: process.env.CONFIDENT_OTEL_ENDPOINT,
           }),
         ],
       },
@@ -96,47 +96,71 @@ export const mastra = new Mastra({
 })
 ```
 
-### Metric collections
+These options are available to you:
 
-Confident AI evaluates incoming traces against metric collections defined in your project. Attach them at the trace level or per span type. Trace-level metrics run against the whole trace, and per-type metrics run against matching spans.
+```typescript
+new ConfidentMastraExporter({
+  apiKey: process.env.CONFIDENT_API_KEY, // Default: CONFIDENT_API_KEY
+  endpoint: process.env.CONFIDENT_OTEL_ENDPOINT, // Default: US servers
+  captureContent: false, // Omit inputs, outputs, and messages
+  maxContentBytes: 512, // Truncate captured content
+  timeoutMillis: 30000, // Flush and shutdown budget
+  resourceAttributes: { 'service.name': 'my-agent' }, // Overrides serviceName
+})
+```
+
+Traces carry Mastra's configured `serviceName` unless `resourceAttributes['service.name']` overrides it. Mastra's own sampling, filters, and span processors run before export, so whatever your pipeline lets through is what Confident AI receives.
+
+## Supported signals
+
+The exporter converts ended Mastra spans into OTLP spans, preserving trace IDs, span IDs, parent IDs, external parent IDs, and original timestamps. It needs no start-event cache, so resumed workflow spans and out-of-order completion export correctly.
+
+- **Agent and workflow execution**: Operation names, timing, status, and the parent-child relationships between steps.
+- **Model calls**: Model details, messages, finish reasons, and [token usage](https://www.confident-ai.com/docs/llm-tracing/features/token-usage-cost).
+- **Tool calls**: Tool names and their [input/output](https://www.confident-ai.com/docs/llm-tracing/features/input-output).
+- **Trace details**: The root operation's name, tags, metadata, and input/output.
+- **Errors**: Failed operations retain their error status to make failures visible in the trace.
+
+This integration exports tracing data. Mastra logs, metrics, scores, and feedback aren't included.
+
+## Custom trace metadata
+
+Metadata and tags passed through Mastra's `tracingOptions` are forwarded to the trace in Confident AI, where you can filter and group by them:
 
 ```typescript
-new DeepEvalExporter({
-  metricCollection: 'trace-metrics', // trace-level
-  llmMetricCollection: 'llm-metrics', // applied to LLM spans
-  agentMetricCollection: 'agent-metrics', // applied to agent spans
-  toolMetricCollectionMap: {
-    search: 'search-tool-metrics', // applied to the "search" tool
+const result = await mastra.getAgent('assistant').generate('How do you make the best coffee?', {
+  tracingOptions: {
+    metadata: { release: '2026-09', tier: 'enterprise' },
+    tags: ['production', 'support'],
   },
 })
 ```
 
-### Complete Configuration
+Your metadata is merged with the fields Mastra sets itself, such as `runId`. Tags apply to the root span, so they land on the trace rather than on individual spans.
+
+## Lifecycle
+
+Mastra owns this exporter. It creates its own OTLP processor and never registers, replaces, or shuts down the global OpenTelemetry provider, so there is no `init()` call to make and no preload to add to your start command.
+
+Spans are batched and sent when the exporter is shut down. Shut it down once, after every agent run and stream has finished, or a short-lived script exits before anything is sent:
 
 ```typescript
-new DeepEvalExporter({
-  apiKey: process.env.CONFIDENT_API_KEY,
-  environment: 'production', // Default: "development"
-  name: 'my-trace', // Default: the Mastra serviceName
-  tags: ['production'],
-  metadata: { team: 'growth' },
-})
+await observability.shutdown()
 ```
 
-## Span type mapping
+In a long-running server, shut down during graceful shutdown rather than per request. Traces can take up to 30 seconds to appear in the Observatory after being sent.
+
+## Threads and trace properties
+
+This exporter maps Mastra's own tracing surface, so trace metadata and tags come from `tracingOptions` as shown above.
 
-Mastra spans map to the span types shown in Confident AI:
+Grouping turns into [threads](https://www.confident-ai.com/docs/llm-tracing/features/threads) and setting trace-level properties such as user IDs use `confident-trace`'s SDK instrumentation, which attaches to Mastra directly rather than through an exporter. See the [Mastra integration guide](https://www.confident-ai.com/docs/integrations/third-party/mastra) for that setup.
 
-| Mastra span type                                                       | Confident AI span type |
-| ---------------------------------------------------------------------- | ---------------------- |
-| `AGENT_RUN`, `WORKFLOW_RUN`                                            | `AGENT`                |
-| `MODEL_GENERATION`                                                     | `LLM`                  |
-| `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `CLIENT_TOOL_CALL` | `TOOL`                 |
-| `RAG_EMBEDDING`, `RAG_VECTOR_OPERATION`                                | `RETRIEVER`            |
-| All other exported span types                                          | `CUSTOM`               |
+Choose one or the other. Do not use both at once.
 
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [DeepEvalExporter reference](https://mastra.ai/reference/observability/tracing/exporters/confident-ai)
-- [Confident AI documentation](https://www.confident-ai.com/docs)
+- [Mastra integration guide](https://www.confident-ai.com/docs/integrations/third-party/mastra)
+- [Online evals](https://www.confident-ai.com/docs/llm-tracing/online-evals)
+- [confident-trace on GitHub](https://github.com/confident-ai/confident-trace)