python-sdk: clarify initialize metadata and async entrypoint (2026-03-16)

Normalize validated initialize metadata back onto InitializeResponse so successful metadata access exposes populated serverInfo fields even when they were derived from userAgent.

Also make async lifecycle guidance explicit in the public surface by documenting async with AsyncCodex() as the preferred entrypoint and aligning the AsyncCodex metadata error message with that model.

Co-authored-by: Codex <noreply@openai.com>

sdk/python/docs/api-reference.md

@@ -62,6 +62,16 @@ with Codex() as codex:
 AsyncCodex(config: AppServerConfig | None = None)
 ```
 
+Preferred usage:
+
+```python
+async with AsyncCodex() as codex:
+    ...
+```
+
+`AsyncCodex` initializes lazily. Context entry is the standard path because it
+ensures startup and shutdown are paired explicitly.
+
 Properties/methods:
 
 - `metadata -> InitializeResponse`

sdk/python/docs/faq.md

@@ -17,6 +17,9 @@ Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout
 
 - `Codex` is the sync public API.
 - `AsyncCodex` is an async replica of the same public API shape.
+- Prefer `async with AsyncCodex()` for async code. It is the standard path for
+  explicit startup/shutdown, and `AsyncCodex` initializes lazily on context
+  entry or first awaited API use.
 
 If your app is not already async, stay with `Codex`.
 

sdk/python/docs/getting-started.md

@@ -61,6 +61,9 @@ with Codex() as codex:
 
 ## 4) Async parity
 
+Use `async with AsyncCodex()` as the normal async entrypoint. `AsyncCodex`
+initializes lazily, and context entry makes startup/shutdown explicit.
+
 ```python
 import asyncio
 from codex_app_server import AsyncCodex, TextInput