docs(migration): note typeless-root outputSchema correctness trade-off (discriminatedUnion case)

Author: felixweinberger

docs/migration.md

@@ -1447,6 +1447,11 @@ being handed a schema their codec cannot parse. When such a tool's handler retur
 or primitive there is invalid 2025 wire data and a strictly-conformant 2025 client would reject the entire response (the fallback included). The text block is what reaches a legacy client; the structured value reaches a 2026 client. While you serve 2025-era clients, keep schemas
 in the 2025 subset (object roots) where you can.
 
+**Typeless-root output schemas are not stamped `type:"object"`.** A Standard-Schema value whose JSON Schema root has no `type` — for example `z.union([z.string(), z.number()])` (`{anyOf:[…]}`), `z.any()` (`{}`), or `z.object({…}).nullable()` — is advertised as-is on the 2026
+era and dropped from the 2025 projection (with the same warn-once). The SDK only defaults `type:"object"` when the root carries `properties`/`patternProperties`/`additionalProperties`/`required`, because stamping it on a typeless union would produce a self-contradictory schema
+(e.g., `{type:"object", anyOf:[{type:"string"}, …]}`) that rejects every value. This is the conservative-correct choice: it means a `z.discriminatedUnion(...)` `outputSchema` (typeless `{oneOf:[{type:"object",…}, …]}`) is also dropped on the 2025 projection even though every
+branch is an object — the previous behavior happened to work for that case by accident. If you need a discriminated-union `outputSchema` advertised on the 2025 era, give it an explicit root `type` via `fromJsonSchema({ type: "object", oneOf: […] })`.
+
 ## Unchanged APIs
 
 The following APIs are unchanged between v1 and v2 (only the import paths changed):