CLI recipes still target v3 traces API; Cloud v4 needs observations v2

[lambi702]

Describe your idea or feedback

The skill is solid for Python SDK v4 instrumentation (references/sdk-upgrade.md matches the official v3→v4 guide: propagate_attributes(), start_observation(), no CallbackHandler(update_trace=...)). It is not aligned for reading data on Langfuse Cloud v4 (observations-first model, already live on Cloud).

What we were doing: pull the latest chat-turn traces from Langfuse Cloud (EU) to check generation model / cost and TOOL ERROR levels, following the skill (npx langfuse-cli, then error-analysis recipes).

What the skill did vs expected:

1. traces list is treated as the primary read path. references/error-analysis.md still has the gotcha --limit > 100 on traces list. On Cloud, npx langfuse-cli api traces list --help now describes legacy-traces, deprecated, with a cut-off of 16 November 2026. It tells agents to use GET /api/public/v2/observations?fromStartTime=&toStartTime= instead. The skill never mentions that replacement, so the agent either hits a CLI that “cannot be called” or falls back to raw curl on /api/public/traces.

2. references/cli.md says “Prefer observations-v2s over observations”. In Python SDK v4 those namespaces were remapped: api.observations_v_2 → api.observations, legacy v1 → api.legacy.*. The CLI OpenAPI names and the SDK names now disagree; the skill does not say which world it is describing, or that Cloud v4 reads should start from Observations API v2 / root observations (Is Root Observation = true), not GET /api/public/traces.

3. Auth env var drift. The skill exports LANGFUSE_HOST. Current CLI docs document LANGFUSE_BASE_URL (with LANGFUSE_HOST as a leftover). Agents following the skill literally can miss the host the CLI actually reads.

This is about the skill recipes, not a product bug. Ingestion via SDK v4 / OTel worked; only the “how to list/get a trace” instructions are stale.

What would the ideal outcome look like?

• SKILL.md / cli.md / error-analysis.md distinguish SDK v4 (write path) from Cloud / API v4 (read path).
• Default recipe for “latest traces” on Cloud: list root observations via Observations API v2 (CLI resource after __schema, not legacy-traces), then fetch children by trace_id.
• Drop or mark as deprecated: traces list pagination tips, prefer observations-v2s.
• Document both LANGFUSE_BASE_URL and LANGFUSE_HOST, and say which the current CLI honors.
• Keep pointing at __schema first — that part already works.