docs: fix discrepancies between docs and source code

docs/api/core/embed.mdx

@@ -34,6 +34,10 @@ export type EmbedParams = EmbedOptions & {
   Optional dimension size for the output embeddings. Not all models support this parameter.
 </ParamField>
 
+<ParamField path="metadata" type="Record<string, unknown>">
+  Custom metadata to attach to the request. Forwarded to observability middleware (OpenTelemetry, Langfuse).
+</ParamField>
+
 <ParamField path="providerOptions" type="EmbedProviderOptions">
   Provider-specific options, namespaced by provider name (e.g. `{ openai: { encodingFormat: 'float' } }`).
 </ParamField>

docs/api/core/errors.mdx

@@ -68,7 +68,7 @@ export class ValidationError extends CoreAIError {
 </ParamField>
 
 <ParamField path="name" type="string">
-  Error name, always `'CoreAIError'`.
+  Error name, matching the class (e.g. `'ValidationError'`, `'ProviderError'`).
 </ParamField>
 
 ### Example

docs/api/core/generate-image.mdx

@@ -43,6 +43,10 @@ export type GenerateImageParams = ImageGenerateOptions & {
   - `'1024x1792'` (portrait)
 </ParamField>
 
+<ParamField path="metadata" type="Record<string, unknown>">
+  Custom metadata to attach to the request. Forwarded to observability middleware (OpenTelemetry, Langfuse).
+</ParamField>
+
 <ParamField path="providerOptions" type="ImageProviderOptions">
   Provider-specific options, namespaced by provider name (e.g. `{ openai: { quality: 'hd' } }`).
 </ParamField>

docs/api/core/generate-object.mdx

@@ -65,6 +65,10 @@ export type GenerateObjectParams<TSchema extends z.ZodType> =
   </Expandable>
 </ParamField>
 
+<ParamField path="metadata" type="Record<string, unknown>">
+  Custom metadata to attach to the request. Forwarded to observability middleware (OpenTelemetry, Langfuse).
+</ParamField>
+
 <ParamField path="providerOptions" type="GenerateProviderOptions">
   Provider-specific options, namespaced by provider name.
 </ParamField>

docs/api/core/generate.mdx

@@ -64,6 +64,10 @@ export type GenerateParams = GenerateOptions & {
   - `{ type: 'tool', toolName: string }` - Force specific tool
 </ParamField>
 
+<ParamField path="metadata" type="Record<string, unknown>">
+  Custom metadata to attach to the request. Forwarded to observability middleware (OpenTelemetry, Langfuse).
+</ParamField>
+
 <ParamField path="providerOptions" type="GenerateProviderOptions">
   Provider-specific options, namespaced by provider name (e.g. `{ openai: { user: '...' } }`).
 </ParamField>

docs/api/core/stream-object.mdx

@@ -59,6 +59,10 @@ export type StreamObjectParams<TSchema extends z.ZodType> =
   Configuration for extended thinking/reasoning capabilities.
 </ParamField>
 
+<ParamField path="metadata" type="Record<string, unknown>">
+  Custom metadata to attach to the request. Forwarded to observability middleware (OpenTelemetry, Langfuse).
+</ParamField>
+
 <ParamField path="providerOptions" type="GenerateProviderOptions">
   Provider-specific options, namespaced by provider name.
 </ParamField>

docs/api/core/stream.mdx

@@ -60,6 +60,10 @@ export type StreamParams = GenerateOptions & {
   Controls how the model uses tools: `'auto'`, `'none'`, `'required'`, or `{ type: 'tool', toolName: string }`.
 </ParamField>
 
+<ParamField path="metadata" type="Record<string, unknown>">
+  Custom metadata to attach to the request. Forwarded to observability middleware (OpenTelemetry, Langfuse).
+</ParamField>
+
 <ParamField path="providerOptions" type="GenerateProviderOptions">
   Provider-specific options, namespaced by provider name.
 </ParamField>

docs/api/core/types.mdx

@@ -261,6 +261,7 @@ type BaseGenerateOptions = {
     maxTokens?: number;
     topP?: number;
     reasoning?: ReasoningConfig;
+    metadata?: Record<string, unknown>;
     providerOptions?: GenerateProviderOptions;
     signal?: AbortSignal;
 };
@@ -428,6 +429,7 @@ type EmbeddingUsage = {
 type EmbedOptions = {
     input: string | string[];
     dimensions?: number;
+    metadata?: Record<string, unknown>;
     providerOptions?: EmbedProviderOptions;
 };
 ```
@@ -450,6 +452,7 @@ type ImageGenerateOptions = {
     prompt: string;
     n?: number;
     size?: string;
+    metadata?: Record<string, unknown>;
     providerOptions?: ImageProviderOptions;
 };
 ```

docs/api/providers/anthropic.mdx

@@ -217,6 +217,16 @@ const result = await generate({
 });
 ```
 
+Effort mapping for adaptive thinking:
+
+| `ReasoningEffort` | Anthropic effort |
+|---|---|
+| `'minimal'` | `'low'` |
+| `'low'` | `'low'` |
+| `'medium'` | `'medium'` |
+| `'high'` | `'high'` |
+| `'max'` | `'max'` (`claude-opus-4-6` only) |
+
 <Note>
   Only `claude-opus-4-6` supports `'max'` effort directly. On `claude-sonnet-4-6`, `'max'` is clamped to `'high'`.
 </Note>
@@ -325,7 +335,7 @@ console.log(result.usage.inputTokenDetails.cacheReadTokens);
 console.log(result.usage.inputTokenDetails.cacheWriteTokens);
 ```
 
-You can request a 1-hour cache TTL when you expect follow-up requests to arrive later than Anthropic's default 5-minute cache window:
+Valid TTL values are `'5m'` (the default) and `'1h'`. Request a longer TTL when you expect follow-up requests to arrive later than Anthropic's default 5-minute cache window:
 
 ```typescript
 const result = await generate({

docs/concepts/configuration.mdx

@@ -18,6 +18,7 @@ type BaseGenerateOptions = {
   maxTokens?: number;
   topP?: number;
   reasoning?: ReasoningConfig;
+  metadata?: Record<string, unknown>;
   providerOptions?: GenerateProviderOptions;
   signal?: AbortSignal;
 };

docs/observability/langfuse.mdx

@@ -125,7 +125,7 @@ Each Langfuse observation includes:
 | `modelParameters` | Temperature, max tokens, top-p (when set) |
 | `input` | Input messages (when `recordContent` is `true`) |
 | `output` | Response content (when `recordContent` is `true`) |
-| `usageDetails` | Input tokens, output tokens, cache tokens, reasoning tokens |
+| `usageDetails` | Token usage with keys: `input`, `output`, `cache_read_input`, `cache_creation_input`, `reasoning_output` (when applicable) |
 | `metadata` | Custom metadata from the options |
 | `level` | Set to `ERROR` on failures |
 | `statusMessage` | Error message on failures |

docs/observability/opentelemetry.mdx

@@ -115,15 +115,24 @@ Spans follow [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io
 
 | Attribute | Description |
 | --- | --- |
-| `gen_ai.system` | Provider name |
+| `gen_ai.provider.name` | Provider name |
 | `gen_ai.request.model` | Model ID |
+| `gen_ai.operation.name` | Operation type (`chat`, `embeddings`, or `image_generation`) |
+| `gen_ai.output.type` | Output type (`text`, `json`, or `image`) |
 | `gen_ai.request.temperature` | Temperature setting |
 | `gen_ai.request.max_tokens` | Max tokens setting |
 | `gen_ai.request.top_p` | Top-p setting |
-| `gen_ai.response.finish_reason` | Why generation stopped |
+| `gen_ai.request.schema_name` | Schema name (for `generateObject`/`streamObject`) |
+| `gen_ai.response.finish_reasons` | Array of finish reasons |
 | `gen_ai.usage.input_tokens` | Input token count |
 | `gen_ai.usage.output_tokens` | Output token count |
+| `gen_ai.usage.cache_read.input_tokens` | Cached input tokens read |
+| `gen_ai.usage.cache_creation.input_tokens` | Tokens written to cache |
+| `core_ai.function_id` | Function ID from `metadata.functionId` |
+| `core_ai.metadata.*` | Custom metadata fields (from the `metadata` option) |
 
-When `recordContent` is enabled, input messages and output content are recorded as additional attributes.
+Span names follow the pattern `{operation} {modelId}`, for example `chat gpt-5-mini`, `embeddings text-embedding-3-small`, or `image_generation gpt-image-1`.
+
+When `recordContent` is enabled, input messages, tool definitions, and output content are recorded as additional attributes (`gen_ai.system_instructions`, `gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.tool.definitions`, `input.value`, `output.value`).
 
 Errors are recorded with `error.type` and the span status is set to `ERROR`.