Align adapter docs with propagate-on-every behavior

Three stale-doc residues from when the adapter consumed trace_info
on the first observation only. The current behavior — propagate on
every observation under each trace_id to avoid v4's last-attribute-
wins display logic clobbering the trace name — got caught by the
integration-test run and the cache+propagation refactored, but
the module header comments and one example-doc paragraph still
described the original "first observation only" path.

Comment / doc text updated; no code change.

Addresses CoPilot PR review feedback on #82.

Author: chris-colinsky

docs/examples/10-langfuse-observability.md

@@ -145,8 +145,10 @@ The adapter bridges `langfuse>=4.6,<5`'s unified `start_observation`
 API onto OA's four-method `LangfuseClient` Protocol. v4 has no
 explicit trace creation (traces are auto-created from observations);
 the adapter caches trace info from `.trace()` and applies it via
-`propagate_attributes` around the first observation, so trace name
-+ metadata land on the trace as Langfuse renders it.
+`propagate_attributes` around EVERY observation under that trace_id.
+Propagating on every observation keeps v4's last-attribute-wins
+display logic from clobbering the trace's display name when later
+observations land without the attribute set.
 
 Validated against `langfuse>=4.6,<5`. v2.x and v3.x are NOT
 supported — supply your own adapter against the same four-method

src/openarmature/observability/langfuse/adapter.py

@@ -8,22 +8,26 @@
 #   - v4 has no explicit `client.trace(...)` — traces are auto-created
 #     when the first observation starts. We cache the trace name +
 #     metadata on `.trace()` and apply them via `propagate_attributes`
-#     around the first observation under that trace_id.
+#     around EVERY observation under that trace_id. Propagating on
+#     every observation (not just the first) keeps v4's
+#     last-attribute-wins display logic from clobbering the trace's
+#     display name when later observations land without the attribute
+#     set.
 #   - v4 unifies span and generation under `start_observation(as_type=)`.
 #     The adapter routes `.span()` to `as_type="span"` and
 #     `.generation()` to `as_type="generation"`.
 #   - v4's `propagate_attributes(metadata=...)` requires Dict[str, str]
 #     (not Dict[str, Any]). Non-string values are JSON-serialized at
 #     the boundary.
 #
-# `update_trace` is best-effort. v4 doesn't expose a clean
-# post-creation trace-update SDK method — we can only mutate trace
-# fields via OTel attributes during observation creation. The current
-# OA LangfuseObserver doesn't actually invoke `update_trace` (caller-
-# supplied invocation-label lands in PR 4 via the
-# `propagate_attributes` path on first observation instead), so the
-# adapter no-ops it and updates the cached pending info in case some
-# future caller needs it before the trace materializes.
+# `update_trace` merges into the persistent trace_info cache so
+# subsequent observations under the trace_id pick up the new values
+# via `propagate_attributes`. Existing observations are NOT
+# retroactively updated. The current OA LangfuseObserver doesn't
+# actually invoke `update_trace` today — caller-supplied
+# invocation-label lands in PR 4 via the trace_info cache before the
+# first observation creates the trace — but the merge-then-propagate
+# path is wired for forward compat.
 
 """LangfuseSDKAdapter: bridge langfuse>=4.6 onto the LangfuseClient Protocol."""