@mastra/mcp-docs-server 1.2.8-alpha.7 → 1.2.8

package/.docs/reference/datasets/datasets-manager.md

@@ -13,9 +13,7 @@ The `DatasetsManager` class provides the public API for managing datasets, inclu
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Create a dataset
 const dataset = await mastra.datasets.create({
@@ -32,9 +30,7 @@ const { datasets } = await mastra.datasets.list()
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Get by ID
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
@@ -50,9 +46,7 @@ Retrieves a specific experiment (run) by ID. Unlike `dataset.getExperiment()`, t
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 // Get experiment directly without knowing the dataset
 const experiment = await mastra.datasets.getExperiment({
@@ -68,9 +62,7 @@ console.log(`Status: ${experiment.status}`)
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const comparison = await mastra.datasets.compareExperiments({
   experimentIds: ['exp-1', 'exp-2'],
@@ -83,9 +75,7 @@ const comparison = await mastra.datasets.compareExperiments({
 `DatasetsManager` isn't instantiated directly. Access it from a `Mastra` instance:
 
 ```typescript
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 const datasetsManager = mastra.datasets
 ```
 

package/.docs/reference/datasets/delete.md

@@ -11,9 +11,7 @@ Deletes a dataset by ID, including all items, versions, and experiments.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 await mastra.datasets.delete({ id: 'dataset-id' })
 ```

package/.docs/reference/datasets/deleteExperiment.md

@@ -11,9 +11,7 @@ Deletes an experiment (run) by ID, including all associated results.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/deleteItem.md

@@ -11,9 +11,7 @@ Deletes a single item from the dataset by ID.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/deleteItems.md

@@ -11,9 +11,7 @@ Deletes multiple items from the dataset in a single bulk operation.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/get.md

@@ -11,9 +11,7 @@ Retrieves an existing dataset by ID. Throws a `MastraError` if the dataset doesn
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getDetails.md

@@ -11,9 +11,7 @@ Retrieves the full dataset record from storage, including metadata, schemas, and
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getExperiment.md

@@ -11,9 +11,7 @@ Retrieves a specific experiment (run) by its ID.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getItem.md

@@ -11,9 +11,7 @@ Retrieves a single dataset item by ID, optionally at a specific dataset version.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/getItemHistory.md

@@ -11,9 +11,7 @@ Retrieves the full SCD-2 (Slowly Changing Dimension Type 2) history of a specifi
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/list.md

@@ -11,9 +11,7 @@ Lists datasets with pagination and optional filters. Filters are applied at the
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const { datasets, pagination } = await mastra.datasets.list({ page: 0, perPage: 10 })
 

package/.docs/reference/datasets/listExperimentResults.md

@@ -11,9 +11,7 @@ Lists individual item results for a specific experiment with optional filters an
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/listExperiments.md

@@ -11,9 +11,7 @@ Lists experiments (runs) for this dataset with optional filters and pagination.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/listItems.md

@@ -11,9 +11,7 @@ Lists items in the dataset. When only `version` is provided, returns a bare `Dat
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/listVersions.md

@@ -11,9 +11,7 @@ Lists all versions of the dataset with pagination.
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/startExperiment.md

@@ -11,9 +11,7 @@ Runs an experiment on the dataset and waits for completion. Executes all items a
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/startExperimentAsync.md

@@ -11,9 +11,7 @@ Starts an experiment asynchronously (fire-and-forget). Returns immediately with
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/update.md

@@ -12,9 +12,7 @@ Updates dataset metadata, name, description, and/or schemas. Use Standard JSON S
 import { Mastra } from '@mastra/core'
 import { z } from 'zod'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/datasets/updateItem.md

@@ -11,9 +11,7 @@ Updates an existing item in the dataset. Only the provided fields are updated. U
 ```typescript
 import { Mastra } from '@mastra/core'
 
-const mastra = new Mastra({
-  /* storage config */
-})
+const mastra = new Mastra({/* storage config */})
 
 const dataset = await mastra.datasets.get({ id: 'dataset-id' })
 

package/.docs/reference/editor/mastra-editor.md

@@ -14,9 +14,7 @@ import { MastraEditor } from '@mastra/editor'
 import { ComposioToolProvider } from '@mastra/editor/providers/composio'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
   editor: new MastraEditor({
     toolProviders: {
       composio: new ComposioToolProvider({

package/.docs/reference/evals/context-recall.md

@@ -0,0 +1,205 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Context recall scorer
+
+The `createContextRecallScorer()` function creates a scorer that evaluates how well retrieved context covers the claims in a ground-truth reference answer. It measures retrieval completeness by checking what fraction of the ground truth's claims are attributable to the retrieved context.
+
+This scorer requires a ground-truth reference answer, making it suitable for labeled datasets in CI or test environments. When `groundTruth` is not provided in the run, the scorer returns a score of 0 rather than throwing an error.
+
+## RAG retrieval evaluation
+
+Ideal for evaluating retrieval completeness in RAG pipelines where:
+
+- You need to verify the retriever fetches all necessary information
+- You have labeled datasets with known-correct answers
+- You want to catch regressions in what the retriever returns
+
+## Dataset-driven testing
+
+Use when running evaluations against curated test sets:
+
+- CI pipelines with ground-truth labeled questions
+- A/B testing retrieval strategies
+- Benchmarking embedding models for coverage
+
+## Parameters
+
+**model** (`MastraModelConfig`): The language model to use for evaluating claim attribution
+
+**options** (`ContextRecallMetricOptions`): Configuration options for the scorer
+
+**Note**: Either `context` or `contextExtractor` must be provided. When both are provided, `contextExtractor` is used only if the run input and output are agent-shaped (`MastraDBMessage[]`); otherwise the scorer falls back to `context`.
+
+## `.run()` returns
+
+**score** (`number`): Recall score between 0 and scale (default 0-1), representing the fraction of ground-truth claims covered by the context
+
+**reason** (`string`): Human-readable explanation of which ground-truth claims were and were not found in the context
+
+## Scoring details
+
+### Claim attribution
+
+Context Recall uses a two-step LLM evaluation followed by a deterministic score calculation:
+
+1. **Claim extraction**: The ground-truth answer is decomposed into atomic claims
+2. **Attribution check**: Each claim is checked against the retrieval context for support
+
+The score is then calculated as the ratio of attributed claims to total claims, multiplied by scale.
+
+### Scoring formula
+
+```text
+Context Recall = attributed_claims / total_claims × scale
+
+Where:
+- attributed_claims = number of ground-truth claims supported by the context
+- total_claims = total number of claims extracted from the ground truth
+- Attribution is binary: a claim is either supported (yes) or not (no)
+```
+
+### Score interpretation
+
+These ranges assume the default `scale` of 1. When using a custom scale, multiply accordingly.
+
+- **0.9-1.0**: Excellent recall — context covers nearly all ground-truth claims
+- **0.7-0.8**: Good recall — most claims are covered, minor gaps
+- **0.4-0.6**: Moderate recall — significant information missing from context
+- **0.1-0.3**: Poor recall — most ground-truth claims not found in context
+- **0.0**: No recall — none of the ground-truth claims are in the context
+
+### Reason analysis
+
+The reason field explains:
+
+- Which ground-truth claims were found in the context
+- Which claims were missing and what information gaps exist
+- Specific context pieces that supported attributed claims
+
+### Optimization insights
+
+Use results to:
+
+- **Improve retrieval**: Identify what types of information the retriever misses
+- **Tune chunk size**: Ensure chunks contain enough detail to cover ground-truth claims
+- **Evaluate embeddings**: Test different embedding models for better information coverage
+- **Expand knowledge base**: Add documents that cover frequently missed claims
+
+### Example calculation
+
+Given ground truth: "Einstein was born in 1879. He developed relativity. He won the Nobel Prize."
+
+Claims extracted: 3
+
+- "Einstein was born in 1879" → attributed (context mentions birthdate)
+- "Einstein developed relativity" → attributed (context covers relativity)
+- "Einstein won the Nobel Prize" → not attributed (context doesn't mention Nobel Prize)
+
+Recall = 2/3 = 0.67
+
+## Scorer configuration
+
+### Dynamic context extraction
+
+```typescript
+const scorer = createContextRecallScorer({
+  model: 'openai/gpt-5.5',
+  options: {
+    contextExtractor: (input, output) => {
+      const query = input?.inputMessages?.[0]?.content || ''
+      const searchResults = vectorDB.search(query, { limit: 10 })
+      return searchResults.map(result => result.content)
+    },
+    scale: 1,
+  },
+})
+```
+
+### Static context evaluation
+
+```typescript
+const scorer = createContextRecallScorer({
+  model: 'openai/gpt-5.5',
+  options: {
+    context: [
+      'Document 1: Einstein was born on 14 March 1879 in Ulm, Germany.',
+      'Document 2: Einstein published the theory of special relativity in 1905.',
+      'Document 3: Einstein moved to the United States in 1933.',
+    ],
+  },
+})
+```
+
+## Example
+
+Evaluate RAG retrieval completeness against a labeled dataset:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createContextRecallScorer } from '@mastra/evals/scorers/prebuilt'
+import { myAgent } from './agent'
+
+const scorer = createContextRecallScorer({
+  model: 'openai/gpt-5.5',
+  options: {
+    contextExtractor: (input, output) => {
+      // Extract context from tool invocation results in the agent output
+      return output
+        .filter(msg => msg?.role === 'assistant')
+        .flatMap(msg => msg?.content?.toolInvocations ?? [])
+        .filter((tool: any) => tool.state === 'result')
+        .map((tool: any) => JSON.stringify(tool.result))
+    },
+  },
+})
+
+const result = await runEvals({
+  data: [
+    {
+      input: 'What are the health benefits of green tea?',
+      groundTruth:
+        'Green tea contains antioxidants that reduce inflammation, L-theanine that improves focus, and catechins that boost metabolism.',
+    },
+    {
+      input: 'How does photosynthesis work?',
+      groundTruth:
+        'Photosynthesis converts sunlight into chemical energy using chlorophyll in chloroplasts, producing glucose and oxygen from carbon dioxide and water.',
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.id].score,
+      reason: scorerResults[scorer.id].reason,
+    })
+  },
+})
+
+console.log(result.scores)
+```
+
+For more details on `runEvals`, see the [runEvals reference](https://mastra.ai/reference/evals/run-evals).
+
+To add this scorer to an agent, see the [Scorers overview](https://mastra.ai/docs/evals/overview) guide.
+
+## Comparison with context precision
+
+Choose the right scorer for your needs:
+
+| Use case                  | Context Recall           | Context Precision             |
+| ------------------------- | ------------------------ | ----------------------------- |
+| **What it measures**      | Coverage of ground truth | Relevance of retrieved chunks |
+| **Direction**             | Ground truth → context   | Context → ground truth        |
+| **Position sensitive**    | No                       | Yes (rewards early placement) |
+| **Requires ground truth** | Yes                      | Yes                           |
+| **Failure mode caught**   | Missing information      | Irrelevant noise              |
+
+Use both together for a complete picture of retrieval quality: precision catches junk in the context, recall catches gaps.
+
+## Related
+
+- [Context Precision Scorer](https://mastra.ai/reference/evals/context-precision): Evaluates if retrieved context is relevant and well-ranked
+- [Context Relevance Scorer](https://mastra.ai/reference/evals/context-relevance): Evaluates context usage and quality
+- [Faithfulness Scorer](https://mastra.ai/reference/evals/faithfulness): Measures answer groundedness in context
+- [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers): Creating your own evaluation metrics

package/.docs/reference/evals/create-scorer.md

@@ -23,18 +23,12 @@ const scorer = createScorer({
     instructions: 'You are an expert evaluator...',
   },
 })
-  .preprocess({
-    /* step config */
-  })
-  .analyze({
-    /* step config */
-  })
+  .preprocess({/* step config */})
+  .analyze({/* step config */})
   .generateScore(({ run, results }) => {
     // Return a number
   })
-  .generateReason({
-    /* step config */
-  })
+  .generateReason({/* step config */})
 ```
 
 ## `createScorer` options

package/.docs/reference/evals/mastra-scorer.md

@@ -33,9 +33,7 @@ const result = await scorer.run({
   input: 'What is machine learning?',
   output: 'Machine learning is a subset of artificial intelligence...',
   runId: 'optional-run-id',
-  requestContext: {
-    /* optional context */
-  },
+  requestContext: {/* optional context */},
 })
 ```
 

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

@@ -16,16 +16,17 @@ import { z } from 'zod'
 
 export default createTool({
   id: 'get_weather',
-  description: 'Get the current weather for a city.',
+  description: 'Get the current weather for a location.',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    tempC: z.number(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ context }) => {
-    return { city: context.city, tempC: 21 }
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```

package/.docs/reference/index.md

@@ -57,6 +57,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [WorkOS](https://mastra.ai/reference/auth/workos)
 - [AgentBrowser](https://mastra.ai/reference/browser/agent-browser)
 - [BrowserViewer](https://mastra.ai/reference/browser/browser-viewer)
+- [FirecrawlBrowser](https://mastra.ai/reference/browser/firecrawl-browser)
 - [MastraBrowser Class](https://mastra.ai/reference/browser/mastra-browser)
 - [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser)
 - [ChannelProvider](https://mastra.ai/reference/channels/channel-provider)
@@ -142,6 +143,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Completeness](https://mastra.ai/reference/evals/completeness)
 - [Content Similarity Scorer](https://mastra.ai/reference/evals/content-similarity)
 - [Context Precision Scorer](https://mastra.ai/reference/evals/context-precision)
+- [Context Recall Scorer](https://mastra.ai/reference/evals/context-recall)
 - [Context Relevance Scorer](https://mastra.ai/reference/evals/context-relevance)
 - [Faithfulness](https://mastra.ai/reference/evals/faithfulness)
 - [Hallucination](https://mastra.ai/reference/evals/hallucination)
@@ -336,6 +338,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Inworld Realtime](https://mastra.ai/reference/voice/inworld-realtime)
 - [LiveKit](https://mastra.ai/reference/voice/livekit)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
+- [Mistral](https://mastra.ai/reference/voice/mistral)
 - [Murf](https://mastra.ai/reference/voice/murf)
 - [OpenAI](https://mastra.ai/reference/voice/openai)
 - [OpenAI Realtime](https://mastra.ai/reference/voice/openai-realtime)
@@ -392,6 +395,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
 - [MesaFilesystem](https://mastra.ai/reference/workspace/mesa-filesystem)
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
+- [PlatformFilesystem](https://mastra.ai/reference/workspace/platform-filesystem)
+- [PlatformSandbox](https://mastra.ai/reference/workspace/platform-sandbox)
 - [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
 - [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
 - [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)

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

@@ -408,6 +408,27 @@ Setting `bufferTokens: false` disables both observation and reflection async buf
 
 Observational Memory emits typed data parts during agent execution that clients can use for real-time UI feedback. These are streamed alongside the agent's response.
 
+### Read extractor results
+
+Both completion events carry extractor output in their `data` payload. The extractor fields are:
+
+```typescript
+interface DataOmObservationEndPart {
+  type: 'data-om-observation-end'
+  data: {
+    /** Whether the completed work was an observation or reflection */
+    operationType: 'observation' | 'reflection'
+    /** Values extracted during this OM operation, keyed by extractor slug */
+    extractedValues?: Record<string, unknown>
+    /** Extractor failures from this OM operation. Successful extractor values are still included */
+    extractionFailures?: Array<{ slug: string; error: string }>
+    // ...other fields documented in the tables below
+  }
+}
+```
+
+Both extractor fields are optional. A completion can include values, failures, both, or neither. `data-om-observation-end` reports synchronous completion. `data-om-buffering-end` reports completed background work whose buffered content still awaits activation, although extractor metadata is already persisted. `DataOmBufferingEndPart` carries the same extractor fields, and both types are exported from `@mastra/memory/processors`. See [Read extracted values from a stream](https://mastra.ai/docs/memory/observational-memory) for a consumer example.
+
 ### `data-om-status`
 
 Emitted once per agent loop step, before model generation. Provides a snapshot of the current memory state, including token usage for both context windows and the state of any async buffered content.

package/.docs/reference/observability/tracing/exporters/posthog.md

@@ -39,6 +39,14 @@ async exportTracingEvent(event: TracingEvent): Promise<void>
 
 Exports a tracing event to PostHog.
 
+### `onFeedbackEvent`
+
+```typescript
+async onFeedbackEvent(event: FeedbackEvent): Promise<void>
+```
+
+Exports a feedback event to PostHog. See [Feedback export](#feedback-export).
+
 ### flush
 
 ```typescript
@@ -92,4 +100,34 @@ const exporter = new PosthogExporter({
 | `AGENT_RUN`          | `$ai_span`         |
 | `WORKFLOW_RUN`       | `$ai_span`         |
 | All other workflows  | `$ai_span`         |
-| `GENERIC`            | `$ai_span`         |
+| `GENERIC`            | `$ai_span`         |
+
+## Feedback export
+
+Feedback recorded with [`addFeedback()`](https://mastra.ai/docs/observability/feedback) is exported to PostHog as a native `$ai_feedback` event. PostHog shows it as **User feedback** on the linked trace. No extra configuration is needed.
+
+```typescript
+const trace = await mastra.observability.getRecordedTrace({ traceId })
+await trace.addFeedback({
+  feedbackType: 'thumbs',
+  value: 'down',
+  comment: 'Wrong answer',
+})
+```
+
+Feedback events map to these PostHog properties:
+
+| Mastra feedback field                  | PostHog property    |
+| -------------------------------------- | ------------------- |
+| `traceId`                              | `$ai_trace_id`      |
+| `comment` (or `value` when no comment) | `$ai_feedback_text` |
+| `feedbackId`                           | `feedback_id`       |
+| `feedbackType`                         | `feedback_type`     |
+| `value`                                | `feedback_value`    |
+| `feedbackSource`                       | `feedback_source`   |
+| `spanId`                               | `span_id`           |
+| `sourceId`                             | `source_id`         |
+| `metadata.sessionId`                   | `$ai_session_id`    |
+| `metadata` (other keys)                | custom properties   |
+
+Feedback without a `traceId` is dropped because PostHog anchors feedback to a trace through `$ai_trace_id`. The event's distinct ID resolves from `feedbackUserId`, then `metadata.userId`, then `defaultDistinctId`, then `anonymous`.