@mastra/mcp-docs-server 1.3.0 → 1.3.1-alpha.2

package/.docs/docs/evals/running-in-ci.md

@@ -14,11 +14,13 @@ You can use any testing framework that supports ESM modules, such as [Vitest](ht
 
 Use `runEvals` to evaluate your agent against multiple test cases. The function accepts an array of data items, each containing an `input` and optional `groundTruth` for scorer validation.
 
+Resolve the `target` with `mastra.getAgent()` or `mastra.getWorkflow()` rather than importing it directly. A directly imported agent or workflow has no Mastra instance attached, so registry lookups inside steps or tools (such as `mastra.getAgent('weatherAgent')`) fail, scores aren't persisted, and trace-based trajectory scoring is unavailable.
+
 ```typescript
 import { describe, it, expect } from 'vitest'
-import { createScorer, runEvals } from '@mastra/core/evals'
-import { weatherAgent } from './weather-agent'
-import { locationScorer } from '../scorers/location-scorer'
+import { runEvals } from '@mastra/core/evals'
+import { mastra } from '../src/mastra'
+import { locationScorer } from '../src/mastra/scorers/location-scorer'
 
 describe('Weather Agent Tests', () => {
   it('should correctly extract locations from queries', async () => {
@@ -37,7 +39,7 @@ describe('Weather Agent Tests', () => {
           groundTruth: { expectedLocation: 'Berlin', expectedCountry: 'RU' },
         },
       ],
-      target: weatherAgent,
+      target: mastra.getAgent('weatherAgent'),
       scorers: [locationScorer],
     })
 
@@ -73,7 +75,7 @@ Create separate test cases for different evaluation scenarios:
 
 ```typescript
 describe('Weather Agent Tests', () => {
-  const locationScorer = createScorer({/* ... */})
+  const weatherAgent = mastra.getAgent('weatherAgent')
 
   it('should handle location disambiguation', async () => {
     const result = await runEvals({

package/.docs/docs/evals/vitest-integration.md

@@ -37,20 +37,15 @@ The setup file registers the custom matchers on `expect`. Alternatively, call `r
 ```typescript
 import { test } from 'vitest'
 import { expectEvals } from '@mastra/evals/vitest'
-import { capitalsAgent } from './capitals-agent'
-import { containsGroundTruth } from '../scorers'
-import { createKeywordCoverageScorer } from '@mastra/evals/scorers/prebuilt'
+import { checks } from '@mastra/evals/checks'
+import { mastra } from '../src/mastra'
 
-test('capitals agent answers with the expected city', { timeout: 60_000 }, async () => {
+test('weather agent calls the tool and answers relevantly', { timeout: 60_000 }, async () => {
   await expectEvals({
-    target: capitalsAgent,
-    data: [
-      { input: 'What is the capital of France?', groundTruth: 'Paris' },
-      { input: 'What is the capital of Japan?', groundTruth: 'Tokyo' },
-      { input: 'What is the capital of Australia?', groundTruth: 'Canberra' },
-    ],
-    gates: [containsGroundTruth],
-    scorers: [{ scorer: createKeywordCoverageScorer(), threshold: 0.4 }],
+    target: mastra.getAgent('weatherAgent'),
+    data: [{ input: "What's the weather in London?" }],
+    gates: [checks.calledTool('weatherTool'), checks.noToolErrors(), checks.includes('London')],
+    scorers: [{ scorer: mastra.getScorer('answerRelevancyScorer'), threshold: 0.7 }],
   }).toPass(0.8)
 })
 ```
@@ -66,18 +61,18 @@ LLM-backed evals are far slower than Vitest's default 5-second timeout, so pass
 ```typescript
 import { test } from 'vitest'
 import { expectEval } from '@mastra/evals/vitest'
-import { capitalsAgent } from './capitals-agent'
-import { containsGroundTruth } from '../scorers'
+import { checks } from '@mastra/evals/checks'
+import { mastra } from '../src/mastra'
 
 test.for([
-  { input: 'What is the capital of France?', groundTruth: 'Paris' },
-  { input: 'What is the capital of Japan?', groundTruth: 'Tokyo' },
-  { input: 'What is the capital of Australia?', groundTruth: 'Canberra' },
-])('capitals agent: $input', { timeout: 60_000 }, async item => {
+  { input: "What's the weather in London?", groundTruth: 'London' },
+  { input: "What's the weather in Tokyo?", groundTruth: 'Tokyo' },
+  { input: "What's the weather in Sydney?", groundTruth: 'Sydney' },
+])('weather agent: $input', { timeout: 60_000 }, async item => {
   await expectEval({
-    target: capitalsAgent,
+    target: mastra.getAgent('weatherAgent'),
     data: item,
-    gates: [containsGroundTruth],
+    gates: [checks.calledTool('weatherTool'), checks.includes(item.groundTruth)],
   }).toPass()
 })
 ```
@@ -91,20 +86,20 @@ For finer-grained control, call `runEvals` directly inside a regular `test()` an
 ```typescript
 import { test, expect } from 'vitest'
 import { runEvals } from '@mastra/core/evals'
-import { supportAgent } from './support-agent'
-import { relevancyScorer, noRefusalScorer } from '../scorers'
+import { checks } from '@mastra/evals/checks'
+import { mastra } from '../src/mastra'
 
-test('support agent quality', { timeout: 60_000 }, async () => {
+test('weather agent quality', { timeout: 60_000 }, async () => {
   const result = await runEvals({
-    target: supportAgent,
-    data: [{ input: 'How do I update my payment method?' }],
-    scorers: [relevancyScorer],
-    gates: [noRefusalScorer],
+    target: mastra.getAgent('weatherAgent'),
+    data: [{ input: "What's the weather in London?" }],
+    scorers: [mastra.getScorer('answerRelevancyScorer')],
+    gates: [checks.noToolErrors()],
   })
 
   expect(result).toHaveVerdict('passed')
   expect(result).toPassGates()
-  expect(result).toHaveScoreAbove('relevancy', 0.7)
+  expect(result).toHaveScoreAbove('answer-relevancy-scorer', 0.7)
 })
 ```
 
@@ -115,6 +110,49 @@ Available matchers:
 - `toPassGates()`: asserts all gates passed. Fails when no gates were configured.
 - `toPassThresholds()`: asserts all scorer thresholds passed. Fails when no thresholds were configured.
 
+## Evaluating a workflow
+
+Workflows are valid targets too. Use a `WorkflowScorerConfig` object for `scorers` to score the workflow output, individual steps, or the step execution trajectory, and reference nested scores with dot-paths in the matchers:
+
+```typescript
+import { test, expect } from 'vitest'
+import { runEvals } from '@mastra/core/evals'
+import { mastra } from '../src/mastra'
+
+test('weather workflow runs fetch-weather then plan-activities', { timeout: 60_000 }, async () => {
+  const result = await runEvals({
+    target: mastra.getWorkflow('weatherWorkflow'),
+    data: [
+      {
+        input: { city: 'London' },
+        expectedTrajectory: {
+          steps: [
+            { stepType: 'workflow_step', name: 'fetch-weather' },
+            { stepType: 'workflow_step', name: 'plan-activities' },
+          ],
+        },
+      },
+      {
+        input: { city: 'Tokyo' },
+        expectedTrajectory: {
+          steps: [
+            { stepType: 'workflow_step', name: 'fetch-weather' },
+            { stepType: 'workflow_step', name: 'plan-activities' },
+          ],
+        },
+      },
+    ],
+    scorers: {
+      trajectory: [mastra.getScorer('trajectoryAccuracyScorer')],
+    },
+  })
+
+  expect(result).toHaveScoreAbove('trajectory.code-trajectory-accuracy-scorer', 0.9)
+})
+```
+
+The `plan-activities` step in this workflow calls `mastra.getAgent('weatherAgent')` at runtime, which only works because the target was resolved with `mastra.getWorkflow()`. See the [`runEvals` reference](https://mastra.ai/reference/evals/run-evals) for the full `WorkflowScorerConfig` shape.
+
 ## Reading the reporter output
 
 `MastraEvalsReporter` prints a score table for every eval test after the run completes:
@@ -122,9 +160,11 @@ Available matchers:
 ```text
 Mastra Evals
 
-✓ capitals agent answers with the expected city (3 items)
-   contains-ground-truth (gate)                    1.0  ✓
-   keyword-coverage-scorer (threshold: min 0.4)    1.0  ✓
+✓ weather agent calls the tool and answers relevantly (1 item)
+   check-called-tool (gate)                        1.0  ✓
+   check-no-tool-errors (gate)                     1.0  ✓
+   check-includes (gate)                           1.0  ✓
+   answer-relevancy-scorer (threshold: min 0.7)    0.9  ✓
 
  Eval runs: 1 (1 passed)
 ```

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. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block updates to the still-visible feedback, and you retry by calling the delete API again. Open-source deployments have no background reconciler. 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. On ClickHouse, delete APIs leave the separate delta cursor table untouched. Its 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. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block updates to the still-visible feedback, and you retry by calling the delete API again. On ClickHouse, the next review update also retries the delete and reports the feedback as not found if the retry succeeds, or saves the new status and returns the delete's error if it fails again. Open-source deployments have no background reconciler. 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. On ClickHouse, delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
 
 ## Query feedback analytics
 

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

@@ -93,9 +93,7 @@ Lightweight deletion is a hide-only operation that marks rows with ClickHouse's
 
 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.
 
-Feedback review-status updates require `ALTER UPDATE` permission on `mastra_feedback_events` and, when delta polling is enabled, `INSERT` permission on `mastra_feedback_events_delta`. These updates wait for the ClickHouse mutation to finish on the server that receives the write, so latency depends on that server's mutation queue. Other replicas apply the mutation through the replication log, so a reader on a lagging replica can briefly see the previous status, and an inactive replica doesn't block the update. They modify the existing feedback row and preserve deletion masks: a concurrent review update cannot recreate deleted feedback. Successful updates remain available through delta polling. If a newer version of the same feedback event is ingested while a review update is in flight, the update is re-applied to that newer version; after repeated conflicts it fails with a conflict error (HTTP 409) and the caller retries.
-
-The status mutation and the delta insert are separate operations. If the delta insert fails, the API returns an error even though the status may have changed, and continued delta polling doesn't recover that notification: later polls from the same cursor never return it, and starting delta mode without a cursor subscribes at the current head. To recover, retry the review update after resolving the error, or reread the feedback with a regular list query.
+Feedback review-status updates read the current row and insert a replacement, so they need `SELECT` and `INSERT` rather than `ALTER UPDATE`, and the insert materialized view publishes each update to delta polling. An update that re-runs a delete also needs the delete permissions listed in [initialization](#initialization). A review update that lands while a delete of the same feedback is in progress re-runs that delete and returns not found, so it can't recreate deleted feedback. A failed delete doesn't block review updates, but the next update retries it: if the retry succeeds, the update returns not found; if it fails again, the new status is saved but the update returns the delete's error. If a network error or a lagging replica lets a review row outlive a successful delete, the next review update of that feedback deletes it again and returns not found.
 
 ### Observability with the legacy domain
 
@@ -372,16 +370,10 @@ const observability = new ObservabilityStorageClickhouseVNext({
 await observability.init()
 ```
 
-In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials still need more than read and insert:
+In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()` from a deployment step that uses elevated credentials. Runtime application credentials need:
 
 - `SELECT` and `INSERT` on the Mastra tables.
 - `ALTER DELETE` on the observability tables you delete from. On ClickHouse 26.6 and earlier, lightweight deletes also require `ALTER UPDATE` on those tables; ClickHouse 26.7 removed that requirement.
-- For feedback review updates, `ALTER UPDATE(reviewStatus)` on `mastra_feedback_events` and `INSERT` on `mastra_feedback_events_delta`.
-
-```sql
-GRANT ALTER UPDATE(reviewStatus) ON <database>.mastra_feedback_events TO <runtime_user>;
-GRANT INSERT ON <database>.mastra_feedback_events_delta TO <runtime_user>;
-```
 
 ## Observability
 

package/.docs/integrations/observability/opentelemetry.md

@@ -861,6 +861,7 @@ Tags are exported as a JSON string in the `mastra.tags` span attribute for broad
 If traces aren't displaying or connecting as expected:
 
 - Verify OTEL SDK is initialized before Mastra (use the `--import` flag or import at the top of the entry point)
+- If you see `[OtelBridge] No OpenTelemetry tracer provider is registered globally`, the bridge can't find a tracer provider. Some frameworks create a provider without registering it globally. Pass that provider directly with `new OtelBridge({ tracerProvider })`. See [setup requirements](https://mastra.ai/reference/observability/tracing/bridges/otel)
 - Ensure the `OtelBridge` is added to your observability config
 - Check that your OTEL backend is running and accessible
 

package/.docs/models/providers/edenai.md

@@ -164,7 +164,7 @@ for await (const chunk of stream) {
 | `edenai/groq/openai/gpt-oss-120b`                                      | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `edenai/groq/openai/gpt-oss-20b`                                       | 131K    |       |           |       |       |       | $0.07      | $0.30       |
 | `edenai/groq/openai/gpt-oss-safeguard-20b`                             | 131K    |       |           |       |       |       | $0.07      | $0.30       |
-| `edenai/infomaniak/mistralai/Ministral-3-14B-Instruct-2512`            | 100K    |       |           |       |       |       | $0.34      | $0.46       |
+| `edenai/infomaniak/mistralai/Ministral-3-14B-Instruct-2512`            | 100K    |       |           |       |       |       | $0.34      | $0.45       |
 | `edenai/ionos/meta-llama/Llama-3.3-70B-Instruct`                       | 128K    |       |           |       |       |       | $0.74      | $0.74       |
 | `edenai/ionos/openai/gpt-oss-120b`                                     | 131K    |       |           |       |       |       | $0.17      | $0.74       |
 | `edenai/minimax/MiniMax-M2`                                            | 205K    |       |           |       |       |       | $0.30      | $1          |
@@ -265,7 +265,7 @@ for await (const chunk of stream) {
 | `edenai/qwen/qwen3.8-max`                                              | 1.0M    |       |           |       |       |       | $2         | $6          |
 | `edenai/qwen/qwen3.8-max-0902`                                         | 1.0M    |       |           |       |       |       | $2         | $6          |
 | `edenai/qwen/qwq-plus`                                                 | 131K    |       |           |       |       |       | $0.80      | $2          |
-| `edenai/scaleway/deepseek-v4-flash-0731`                               | 256K    |       |           |       |       |       | $0.46      | $0.91       |
+| `edenai/scaleway/deepseek-v4-flash-0731`                               | 256K    |       |           |       |       |       | $0.45      | $0.91       |
 | `edenai/scaleway/gemma-3-27b-it`                                       | 40K     |       |           |       |       |       | $0.29      | $0.57       |
 | `edenai/scaleway/gpt-oss-120b`                                         | 128K    |       |           |       |       |       | $0.17      | $0.68       |
 | `edenai/scaleway/llama-3.3-70b-instruct`                               | 128K    |       |           |       |       |       | $1         | $1          |

package/.docs/models/providers/kilo.md

@@ -43,11 +43,11 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $4         | $20         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
 | `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.04      | $1          |
-| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.39      | $3          |
+| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.39      | $1          |
 | `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.03      | $0.32       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
-| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $1         | $11         |
+| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $1         | $12         |
 | `kilo/~openai/gpt-astra-latest`                                 | 1.1M    |       |           |       |       |       | $10        | $50         |
 | `kilo/~openai/gpt-luna-latest`                                  | 1.1M    |       |           |       |       |       | $0.10      | $0.50       |
 | `kilo/~openai/gpt-mini-latest`                                  | 400K    |       |           |       |       |       | $0.75      | $5          |
@@ -55,7 +55,7 @@ for await (const chunk of stream) {
 | `kilo/~openai/gpt-terra-latest`                                 | 1.1M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~x-ai/grok-latest`                                        | 500K    |       |           |       |       |       | $2         | $5          |
 | `kilo/~z-ai/glm-flash-latest`                                   | 1.0M    |       |           |       |       |       | $0.04      | $0.14       |
-| `kilo/~z-ai/glm-latest`                                         | 1.0M    |       |           |       |       |       | $0.56      | $3          |
+| `kilo/~z-ai/glm-latest`                                         | 1.0M    |       |           |       |       |       | $0.56      | $2          |
 | `kilo/aion-labs/aion-2.0`                                       | 131K    |       |           |       |       |       | $0.80      | $2          |
 | `kilo/aion-labs/aion-3.0`                                       | 131K    |       |           |       |       |       | $3         | $6          |
 | `kilo/aion-labs/aion-3.0-mini`                                  | 131K    |       |           |       |       |       | $0.70      | $1          |
@@ -386,7 +386,7 @@ for await (const chunk of stream) {
 | `kilo/tencent/hy-mt2-1.8b`                                      | 8K      |       |           |       |       |       | $0.04      | $0.18       |
 | `kilo/tencent/hy-mt2-30b-a3b`                                   | 8K      |       |           |       |       |       | $0.07      | $0.29       |
 | `kilo/tencent/hy-mt2-7b`                                        | 8K      |       |           |       |       |       | $0.07      | $0.29       |
-| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.13      | $0.53       |
+| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.08      | $0.33       |
 | `kilo/tencent/hy3-preview`                                      | 262K    |       |           |       |       |       | $0.18      | $0.60       |
 | `kilo/tencent/hy4-preview`                                      | 1.0M    |       |           |       |       |       | $0.83      | $3          |
 | `kilo/thedrummer/cydonia-24b-v4.1`                              | 131K    |       |           |       |       |       | $0.30      | $0.50       |

package/.docs/reference/evals/run-evals.md

@@ -10,17 +10,16 @@ The `runEvals` function enables batch evaluation of agents and workflows by runn
 
 ```typescript
 import { runEvals } from '@mastra/core/evals'
-import { myAgent } from './agents/my-agent'
-import { myScorer1, myScorer2 } from './scorers'
+import { mastra } from './mastra'
 
 const result = await runEvals({
-  target: myAgent,
+  target: mastra.getAgent('myAgent'),
   data: [
     { input: 'What is machine learning?' },
     { input: 'Explain neural networks' },
     { input: 'How does AI work?' },
   ],
-  scorers: [myScorer1, myScorer2],
+  scorers: [mastra.getScorer('myScorer1'), mastra.getScorer('myScorer2')],
   targetOptions: { maxSteps: 5 },
   concurrency: 2,
   onItemComplete: ({ item, targetResult, scorerResults }) => {
@@ -33,15 +32,17 @@ console.log(`Average scores:`, result.scores)
 console.log(`Processed ${result.summary.totalItems} items`)
 ```
 
+Resolve the `target` from the `Mastra` instance with `mastra.getAgent()` or `mastra.getWorkflow()` rather than importing the agent or workflow directly. A directly imported target has no Mastra instance attached, so registry lookups made during execution (a step calling `mastra.getAgent()`, a child workflow, an `.agent('agent-id')` reference, a tool calling `mastra.getWorkflow()`) fail, scores aren't persisted, and trace-based trajectory extraction is unavailable. `runEvals` logs a warning when the target isn't registered.
+
 ### Multi-turn evaluation
 
 ```typescript
 import { runEvals } from '@mastra/core/evals'
 import { checks } from '@mastra/evals/checks'
-import { weatherAgent } from './agents/weather-agent'
+import { mastra } from './mastra'
 
 const result = await runEvals({
-  target: weatherAgent,
+  target: mastra.getAgent('weatherAgent'),
   data: [
     {
       inputs: [
@@ -60,13 +61,16 @@ const result = await runEvals({
 ```typescript
 import { runEvals } from '@mastra/core/evals'
 import { checks } from '@mastra/evals/checks'
-import { faithfulnessScorer } from './scorers'
+import { mastra } from './mastra'
 
 const result = await runEvals({
-  target: myAgent,
+  target: mastra.getAgent('weatherAgent'),
   data: [{ input: 'What is the weather in Brooklyn?' }],
   gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
-  scorers: [{ scorer: faithfulnessScorer, threshold: 0.7 }, checks.includes('Brooklyn')],
+  scorers: [
+    { scorer: mastra.getScorer('faithfulnessScorer'), threshold: 0.7 },
+    checks.includes('Brooklyn'),
+  ],
 })
 
 result.verdict // 'passed' | 'scored' | 'failed'
@@ -173,7 +177,7 @@ import { runEvals } from '@mastra/core/evals'
 import { checks } from '@mastra/evals/checks'
 
 const result = await runEvals({
-  target: weatherAgent,
+  target: mastra.getAgent('weatherAgent'),
   data: [{ input: 'What is the weather in Brooklyn?' }],
   gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
   scorers: [
@@ -213,7 +217,7 @@ const myScorer = createScorer({
 })
 
 const result = await runEvals({
-  target: chatAgent,
+  target: mastra.getAgent('chatAgent'),
   data: [
     {
       input: 'What is AI?',
@@ -240,7 +244,7 @@ import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/code/t
 const trajectoryScorer = createTrajectoryAccuracyScorerCode()
 
 const result = await runEvals({
-  target: chatAgent,
+  target: mastra.getAgent('chatAgent'),
   data: [
     {
       input: 'What is the weather in London?',
@@ -265,7 +269,7 @@ Pass execution options like `maxSteps` or `modelSettings` to customize agent beh
 
 ```typescript
 const result = await runEvals({
-  target: chatAgent,
+  target: mastra.getAgent('chatAgent'),
   data: [{ input: 'Summarize this article' }, { input: 'Translate to French' }],
   scorers: [relevancyScorer],
   targetOptions: {
@@ -277,9 +281,11 @@ const result = await runEvals({
 
 ### Workflow Evaluation
 
+Resolve the workflow with `mastra.getWorkflow()` so steps that call `mastra.getAgent()` or run child workflows can reach the registry:
+
 ```typescript
 const workflowResult = await runEvals({
-  target: myWorkflow,
+  target: mastra.getWorkflow('myWorkflow'),
   data: [
     { input: { query: 'Process this data', priority: 'high' } },
     { input: { query: 'Another task', priority: 'low' } },
@@ -309,7 +315,7 @@ Add trajectory scoring to workflow evaluations to validate step execution order:
 
 ```typescript
 const workflowResult = await runEvals({
-  target: myWorkflow,
+  target: mastra.getWorkflow('myWorkflow'),
   data: [
     {
       input: { query: 'Process this data' },
@@ -340,7 +346,7 @@ Use `startOptions` on individual data items to customize each workflow run. Per-
 
 ```typescript
 const result = await runEvals({
-  target: myWorkflow,
+  target: mastra.getWorkflow('myWorkflow'),
   data: [
     {
       input: { query: 'hello' },
@@ -362,7 +368,7 @@ Use `inputs` to send sequential turns on a shared thread. Scorers see the accumu
 
 ```typescript
 const result = await runEvals({
-  target: chatAgent,
+  target: mastra.getAgent('chatAgent'),
   data: [
     {
       inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
@@ -385,7 +391,7 @@ Use `turns` to attach `gates`/`scorers` to individual turns. Each per-turn asser
 
 ```typescript
 const result = await runEvals({
-  target: chatAgent,
+  target: mastra.getAgent('chatAgent'),
   data: [
     {
       turns: [

package/.docs/reference/evals/trajectory-accuracy.md

@@ -221,7 +221,7 @@ const scorer = createTrajectoryAccuracyScorerCode({
 const scorer = createTrajectoryAccuracyScorerCode()
 
 await runEvals({
-  target: myAgent,
+  target: mastra.getAgent('myAgent'),
   scorers: { trajectory: [scorer] },
   data: [
     {
@@ -245,16 +245,20 @@ await runEvals({
 
 ### Evaluation modes
 
-The code-based scorer operates in two modes based on `strictOrder`:
+The code-based scorer operates in one of three modes based on `ordering`:
 
-#### Strict mode (`strictOrder: true`)
+#### Strict mode (`ordering: 'strict'`)
 
-Requires an exact match. The actual steps must match the expected steps in the same order with no extra or missing steps. Returns `1.0` for an exact match and `0.0` otherwise.
+Only an exact match (the same steps in the same order, with nothing extra or missing) scores `1.0`. Anything else gets partial credit for the expected steps that matched in position, with a penalty deducted for each extra step. For example, the two expected steps followed by one extra step scores `0.75`.
 
-#### Relaxed mode (`strictOrder: false`, default)
+#### Relaxed mode (`ordering: 'relaxed'`, default)
 
 Allows extra steps. Expected steps must appear in the correct relative order. The score is calculated based on how many expected steps were matched, with optional penalties for extra or repeated steps.
 
+#### Unordered mode (`ordering: 'unordered'`)
+
+Only checks that each expected step is present. Order is ignored, and extra steps are reported in the result but not penalized.
+
 ## Code-based scoring details
 
 - **Continuous scores**: Returns values between 0.0 and 1.0 in relaxed mode; binary (0 or 1) in strict mode
@@ -303,16 +307,16 @@ const scorer = createTrajectoryAccuracyScorerCode({
       { stepType: 'tool_call', name: 'fetch-tool' },
     ],
   },
-  comparisonOptions: { strictOrder: true },
+  comparisonOptions: { ordering: 'strict' },
 })
 
 const result = await runEvals({
-  target: myAgent,
+  target: mastra.getAgent('myAgent'),
   scorers: { trajectory: [scorer] },
   data: [{ input: 'Get my data' }],
 })
 
-console.log(result.scores.trajectory['trajectory-accuracy']) // 1.0
+console.log(result.scores.trajectory['code-trajectory-accuracy-scorer']) // 1.0
 ```
 
 ### Agent trajectory with relaxed ordering
@@ -327,7 +331,7 @@ const scorer = createTrajectoryAccuracyScorerCode({
       { stepType: 'tool_call', name: 'summarize-tool' },
     ],
   },
-  comparisonOptions: { strictOrder: false },
+  comparisonOptions: { ordering: 'relaxed' },
 })
 
 // Agent called search-tool → log-tool → summarize-tool
@@ -354,12 +358,12 @@ const scorer = createTrajectoryAccuracyScorerCode({
 })
 
 const result = await runEvals({
-  target: myWorkflow,
+  target: mastra.getWorkflow('myWorkflow'),
   scorers: { trajectory: [scorer] },
   data: [{ input: { data: 'test' } }],
 })
 
-console.log(result.scores.trajectory['trajectory-accuracy'])
+console.log(result.scores.trajectory['code-trajectory-accuracy-scorer'])
 ```
 
 ### Comparing step data
@@ -517,7 +521,7 @@ const scorer = createTrajectoryScorerCode({
 })
 
 const result = await runEvals({
-  target: myAgent,
+  target: mastra.getAgent('myAgent'),
   scorers: { trajectory: [scorer] },
   data: [
     {
@@ -583,7 +587,7 @@ const trajectoryScorer = createTrajectoryAccuracyScorerCode({
 })
 
 const result = await runEvals({
-  target: myAgent,
+  target: mastra.getAgent('myAgent'),
   scorers: {
     agent: [qualityScorer], // receives raw MastraDBMessage[] output
     trajectory: [trajectoryScorer], // receives pre-extracted Trajectory
@@ -592,7 +596,7 @@ const result = await runEvals({
 })
 
 // result.scores.agent['quality'] — agent-level score
-// result.scores.trajectory['trajectory-accuracy'] — trajectory score
+// result.scores.trajectory['code-trajectory-accuracy-scorer'] — trajectory score
 ```
 
 ### Workflow trajectory evaluation
@@ -612,7 +616,7 @@ const workflowTrajectoryScorer = createTrajectoryAccuracyScorerCode({
 })
 
 const result = await runEvals({
-  target: myWorkflow,
+  target: mastra.getWorkflow('myWorkflow'),
   scorers: {
     workflow: [outputScorer], // receives workflow output
     trajectory: [workflowTrajectoryScorer], // receives pre-extracted Trajectory from step results
@@ -621,7 +625,7 @@ const result = await runEvals({
 })
 
 // result.scores.workflow['output-quality'] — workflow-level score
-// result.scores.trajectory['trajectory-accuracy'] — trajectory score
+// result.scores.trajectory['code-trajectory-accuracy-scorer'] — trajectory score
 ```
 
 ## Related

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

@@ -186,6 +186,7 @@ const memory = new Memory({
 - Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
 - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
 - `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
+- When `workingMemory.schema` is set, `WorkingMemoryExtractor` validates each update against that schema before saving it. If an update doesn't match, it's skipped and reported as an extraction failure while the previous working memory stays in place. Because the schema isn't sent to the model as a structured output constraint, one invalid working memory update can't fail other extractors. A `null` in an optional field is treated as not provided.
 - `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor` and defaults `workingMemory.agentManaged` to `false`. It defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
 - Extraction failures are reported in OM marker data and don't discard other successful extracted values.
 

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

@@ -138,7 +138,7 @@ await mastraClient.deleteFeedback({
 
 Returns `Promise<{ success: boolean }>` from `mastraClient.deleteFeedback()` and the HTTP route. The storage domain method returns `Promise<void>`. Requests with more than 1,000 ids return `400`, and a server running `@mastra/core` older than `1.66.0` returns `501`. ClickHouse vNext, PostgreSQL vNext, DuckDB, and the in-memory store implement deletion. Every other adapter, including LibSQL and MongoDB, throws `OBSERVABILITY_STORAGE_DELETE_FEEDBACK_NOT_IMPLEMENTED`.
 
-On ClickHouse, deletion uses lightweight deletes on the main feedback events table to remove rows from reads, including OLAP queries, 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. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block `updateFeedbackReviewStatus()` on the still-visible feedback, and you retry by calling `deleteFeedback()` again. Open-source deployments have no background reconciler. ClickHouse applies a TTL to deletion requests only when all five signals have finite retention. See [ClickHouse native TTL](https://mastra.ai/reference/storage/retention). Delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
+On ClickHouse, deletion uses lightweight deletes on the main feedback events table to remove rows from reads, including OLAP queries, 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. Each request is marked applied once its delete succeeds; if the delete fails, the request stays unapplied, doesn't block `updateFeedbackReviewStatus()` on the still-visible feedback, and you retry by calling `deleteFeedback()` again. `updateFeedbackReviewStatus()` also retries the delete and throws a not-found error if the retry succeeds, or saves the new status and throws the delete's error if it fails again. Open-source deployments have no background reconciler. ClickHouse applies a TTL to deletion requests only when all five signals have finite retention. See [ClickHouse native TTL](https://mastra.ai/reference/storage/retention). Delete APIs leave the separate delta cursor table untouched. Its rows contain identifiers rather than feedback payloads and expire within two days.
 
 ### `deleteScores(args)`
 

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -11,7 +11,7 @@ Enables bidirectional integration between Mastra tracing and OpenTelemetry infra
 ## Constructor
 
 ```typescript
-new OtelBridge()
+new OtelBridge(config?: OtelBridgeConfig)
 ```
 
 ## Methods
@@ -118,9 +118,18 @@ const mastra = new Mastra({
 })
 ```
 
-## `OpenTelemetry` setup requirements
+## Setup requirements
 
-The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
+The bridge creates spans through an OpenTelemetry tracer provider. For Mastra spans to be exported:
+
+- **A tracer provider must be available.** Register one globally before Mastra runs, for example by calling `sdk.start()` on `NodeSDK` from `@opentelemetry/sdk-node`, or by calling `trace.setGlobalTracerProvider(provider)`. If the provider isn't registered globally, pass it with `new OtelBridge({ tracerProvider })`.
+- **A context manager must be installed for Mastra spans to nest under outer spans.** `NodeSDK` installs one automatically. Without a context manager, spans are still exported, but Mastra root spans can't read the active span, so they start new traces instead of joining the outer trace.
+
+When no tracer provider is available, agents and workflows still run, but no Mastra spans are exported through OpenTelemetry. The bridge logs this warning once:
+
+```text
+[OtelBridge] No OpenTelemetry tracer provider is registered globally, so Mastra spans will not be exported through OpenTelemetry. ...
+```
 
 See the [OtelBridge Guide](https://mastra.ai/integrations/observability/opentelemetry) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
 

package/.docs/reference/observability/tracing/spans.md

@@ -51,7 +51,7 @@ interface BaseSpan<TType extends SpanType> {
 
   /** Snapshot of the RequestContext */
   requestContext?: Record<string, any>
-  /** Is an event span? (occurs at startTime, has no endTime) */
+  /** Is an event span? (point-in-time: endTime equals startTime) */
   isEvent: boolean
 }
 ```
@@ -133,7 +133,7 @@ createEventSpan<TChildType extends SpanType>(
 ): Span<TChildType>
 ```
 
-Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.
+Creates an event span under this span. Event spans represent point-in-time occurrences with no duration. They're emitted as soon as they're created, with `isEvent: true` and an `endTime` equal to their `startTime`, so stored and exported records have `endedAt` equal to `startedAt`.
 
 ## `ExportedSpan`