docs(functions): clarify where invoke metadata reaches code functions

The invoke() docstring said top-level metadata is passed to the function
as its metadata argument. That holds for prompts ({{metadata}}), but code
functions receive it through the hooks, while the handler's metadata
argument is read from input. Document this and show how to nest metadata
in input. Mirrors braintrustdata/braintrust-sdk-python#1073.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: AbhiPrasad

.changeset/clarify-invoke-metadata-docs.md

@@ -0,0 +1,5 @@
+---
+"braintrust": patch
+---
+
+docs(functions): clarify where invoke metadata reaches code functions

js/src/functions/invoke.ts

@@ -78,8 +78,10 @@ export interface InvokeFunctionArgs<
 
   /**
    * Additional metadata to add to the span. This will be logged as the `metadata` field in the span.
-   * It will also be available as the {{metadata}} field in the prompt and as the `metadata` argument
-   * to the function.
+   * It will also be available as the {{metadata}} field in the prompt. For code functions, it is passed
+   * through the hooks (the handler's second argument in TypeScript, `hooks.metadata` in Python), not
+   * as the handler's `metadata` argument, which is read from `input`. To fill the handler's `metadata`
+   * argument, nest it in `input`, e.g. `invoke({ ..., input: { input: ..., metadata: { ... } } })`.
    */
   metadata?: Record<string, unknown>;
   /**