quiver-cli 1.3.1 → 2.0.0

package/template/.agents/skills/integrations/langfuse/SKILL.md

@@ -1,150 +0,0 @@
----
-name: langfuse
-description: >-
-  Interact with Langfuse and access its documentation: tracing, monitoring, creating datasets, running experiments, and evaluating AI applications. Use when needing to (1) query or modify Langfuse data, (2) look up Langfuse documentation, concepts, integration guides, a feature or SDK usage, or (3) do any AI engineering task (AI observability, prompt engineering/management, evaluation and evaluator management, experimentation, dataset management, evaluation-driven CI/CD, feedback collection). Invoke it for tasks in this scope even when Langfuse is not configured or explicitly mentioned.
-allowed-tools:
-  - WebFetch(domain:langfuse.com)
-  - Bash(curl *langfuse.com/*)
-  - Bash(npx langfuse-cli api __schema *)
-  - Bash(npx langfuse-cli api * --help *)
-  - Bash(npx langfuse-cli api * list *)
-  - Bash(npx langfuse-cli api * get *)
-  - Bash(bunx langfuse-cli api __schema *)
-  - Bash(bunx langfuse-cli api * --help *)
-  - Bash(bunx langfuse-cli api * list *)
-  - Bash(bunx langfuse-cli api * get *)
----
-
-# Langfuse
-
-This skill helps you use Langfuse effectively across all common workflows: instrumenting applications, migrating prompts, debugging traces, and accessing data programmatically.
-
-## Core Principles
-
-Follow these principles for ALL Langfuse work:
-
-1. **Documentation First**: NEVER implement based on memory. Always fetch current docs before writing code (Langfuse updates frequently) See the section below on how to access documentation.
-2. **CLI for Data Access**: Use `langfuse-cli` when querying/modifying Langfuse data. See the section below on how to use the CLI.
-3. **Best Practices by Use Case**: Read the relevant reference below use-case-specific guidelines before asking the user for more details or implementing.
-4. **Use latest Langfuse versions**: Unless the user specified otherwise or there's a good reason, always use the latest version of Langfuse SDKs/APIs. Even if you're only creating a plan for another agent to execute, be explicit about the exact version to use.
-5. **If you guide the user through UI** and are unsure about a label or location, inspect the user’s screenshots or ask to see the relevant screen. Do not assume UI labels have the exact same names as API, SDK, or CLI fields.
-
-
-## Use case specific references
-
-- instrumenting an existing function/application: references/instrumentation.md
-- creating or getting to a good (evaluation) dataset to measure quality or test for regressions in AI systems: references/create-dataset.md
-- migrating prompts from a codebase into Langfuse: references/prompt-migration.md
-- creating a prompt or changing any part of an existing prompt, including small edits and debugging/tuning: references/prompt-engineering.md
-- setting up evals when the user needs to identify gaps across signal capture, monitoring, and evaluator metrics ("I have traces, how do I set up evals?"): references/setting-up-evals.md
-- capturing user feedback (thumbs, ratings, implicit signals) as scores on traces: references/user-feedback.md
-- further tips on using the Langfuse CLI: references/cli.md
-- upgrading or migrating Langfuse SDKs and preserving application instrumentation attributes: references/sdk-upgrade.md
-- upgrading legacy trace-level or dataset-item evaluators to observation-level or experiment evaluators: references/trace-evaluator-upgrade.md. Use the [evaluator migration guide](https://langfuse.com/faq/all/llm-as-a-judge-migration) as the primary reference.
-- preparing a Langfuse project for the v4 platform migration: references/v4-project-migration.md
-- judge calibration (LLM-as-a-Judge reliability, simple accuracy checks, advanced split-based validation, confusion matrices, and metric ingestion): references/judge-calibration.md
-- systematic error analysis when requested directly or eval setup still lacks concrete failure modes after agent-led trace inspection: references/error-analysis.md
-- setting up CI/CD experiment gates with `langfuse/experiment-action`: references/ci-cd.md
-- submitting feedback about this skill: references/skill-feedback.md
-
-
-## 1. Langfuse API via CLI
-
-Use the `langfuse-cli` to interact with the full Langfuse REST API from the command line. Run via npx (no install required):
-
-Start by discovering the schema and available arguments:
-
-```bash
-# Discover all available resources
-npx langfuse-cli api __schema
-
-# List actions for a resource
-npx langfuse-cli api <resource> --help
-
-# Show args/options for a specific action
-npx langfuse-cli api <resource> <action> --help
-```
-
-### Credentials
-
-Set environment variables before making calls:
-
-```bash
-export LANGFUSE_PUBLIC_KEY=pk-lf-...
-export LANGFUSE_SECRET_KEY=sk-lf-...
-export LANGFUSE_BASE_URL=https://cloud.langfuse.com # example for EU cloud. For US cloud it's us.cloud.langfuse.com, and can also be a self-hosted URL. The server must always be specified in order to access Langfuse.
-```
-If `LANGFUSE_BASE_URL` is used instead of `LANGFUSE_HOST`, run `export LANGFUSE_HOST="$LANGFUSE_BASE_URL"`.
-If not set, ask the user to set them in their shell or a `.env` file. Keys are found in the Langfuse project under Settings -> API Keys; the user should create a project API key pair there. If they do not have a Langfuse account yet, share that they can create one for free at `https://langfuse.com/cloud`. Do not ask them to paste keys into chat for security reasons.
-
-### Detailed CLI Reference
-
-For common workflows, tips, and full usage patterns, see [references/cli.md](references/cli.md).
-
-## 2. Langfuse Documentation
-
-Three methods to access Langfuse docs, in order of preference. **Always prefer your application's native web fetch and search tools** (e.g., `WebFetch`, `WebSearch`, `mcp_fetch`, etc.) over `curl` when available. The URLs and patterns below work with any fetching method — the `curl` examples are just illustrative.
-
-### 2a. Documentation Index (llms.txt)
-
-Fetch the full index of all documentation pages:
-
-```bash
-curl -s https://langfuse.com/llms.txt
-```
-
-Returns a structured list of every doc page with titles and URLs. Use this to discover the right page for a topic, then fetch that page directly.
-
-Alternatively, you can start on `https://langfuse.com/docs` and explore the site to find the page you need.
-
-### 2b. Fetch Individual Pages as Markdown
-
-Any page listed in llms.txt can be fetched as markdown by appending `.md` to its path or by using `Accept: text/markdown` in the request headers. Use this when you know which page contains the information needed. Returns clean markdown with code examples and configuration details.
-
-```bash
-curl -s "https://langfuse.com/docs/observability/overview.md"
-curl -s "https://langfuse.com/docs/observability/overview" -H "Accept: text/markdown"
-```
-
-### 2c. Search Documentation
-
-When you need to find information across all docs and github issues/discussions without knowing the specific page:
-
-```bash
-curl -s "https://langfuse.com/api/search-docs?query=<url-encoded-query>"
-```
-
-Example:
-
-```bash
-curl -s "https://langfuse.com/api/search-docs?query=How+do+I+trace+LangGraph+agents"
-```
-
-Returns a JSON response with:
-
-- `query`: the original query
-- `answer`: a JSON string containing an array of matching documents, each with:
-  - `url`: link to the doc page
-  - `title`: page title
-  - `source.content`: array of relevant text excerpts from the page
-
-Search is a great fallback if you cannot find the relevant pages or need more context. Especially useful when debugging issues as all GitHub Issues and Discussions are also indexed. Responses can be large — extract only the relevant portions. Note that changelog posts may also surface here: use them only to confirm a feature exists, never to implement from — their examples may be outdated, so always implement from the docs and API/SDK reference.
-
-### Documentation Workflow
-
-1. Start with **llms.txt** to orient — scan for relevant page titles
-2. **Fetch specific pages** when you identify the right one
-3. Fall back to **search** when the topic is unclear and you want more context
-
-## Skill Feedback
-
-When the user expresses that something about this skill is not working as expected, gives incorrect guidance, is missing information, or could be improved — offer to submit feedback to the Langfuse skill maintainers. This includes when:
-
-- The skill gave wrong or outdated instructions
-- A workflow didn't produce the expected result
-- The user wishes the skill covered something it doesn't
-- The user explicitly says something like "this should work differently" or "this is wrong"
-
-**Do NOT trigger this** for issues with Langfuse itself (the product) — only for issues with this skill's instructions and behavior.
-
-When triggered, follow the process in [references/skill-feedback.md](references/skill-feedback.md).

package/template/.agents/skills/integrations/langfuse/references/ci-cd.md

@@ -1,41 +0,0 @@
----
-name: langfuse-ci-cd
-description: Set up or extend agent regression checks / gating in GitHub Actions CI/CD using `langfuse/experiment-action`.
-metadata:
-  required_access:
-    - CODEBASE
-    - LANGFUSE_PROJECT_INTERFACE
-    - LANGFUSE_PROJECT_SCRIPT
-    - GITHUB
----
-
-# Langfuse CI/CD
-
-## Checklist
-
-- [ ] Follow the [CI/CD docs page](https://langfuse.com/docs/evaluation/experiments/experiments-ci-cd) and the [langfuse/experiment-action README](https://github.com/langfuse/experiment-action)
-- [ ] Inspect whether the local repository is a GitHub repo. If not, `langfuse/experiment-action` is not applicable. Follow the guide for other [CI/CD systems](https://langfuse.com/docs/evaluation/experiments/experiments-ci-cd#other-cicd-systems) instead
-- [ ] Ask the user which [evaluators and run evaluators](https://langfuse.com/docs/evaluation/experiments/experiments-via-sdk#evaluators) they want to set up
-- [ ] Ask the user if and when yes which regression thresholds they want to set
-- [ ] Confirm dataset existence and shape of the dataset items before writing code with the Langfuse CLI (see `references/cli.md`)
-  - `langfuse-cli api datasets list`
-  - `langfuse-cli api dataset-items list --dataset-name <dataset name> --limit 5`
-- [ ] Propose the user to verify the check by actually running the new CI check (e.g. by creating a pull request)
-- [ ] If the evaluator task uses a third-party dependency, add the necessary CI steps to install them
-
-### GitHub specific checklist
-- [ ] Ask the user how they want the [workflow to be triggered](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)
-- [ ] If available, use the `gh` CLI to check secret existence / set secrets for:
-      - Langfuse credentials
-      - Credentials required by the evaluator task (e.g. OpenAI or Anthropic API keys)
-
-## Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| `gh` is missing or not authenticated | Install the GitHub CLI if needed, then run `gh auth status` and `gh auth login` before using `gh secret` or `gh workflow` commands. |
-| Local Langfuse environment variables are not set | Set `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_HOST` locally before using `langfuse-cli`; do not ask the user to paste secret values into chat. |
-| Workflow secrets or action inputs are wrong | Verify `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `langfuse_base_url`, and provider secrets exist in the target repo/environment and are passed to the action step. |
-| Forked PR cannot access secrets | GitHub restricts secret access for forked PRs. Document the limitation or choose a trusted trigger such as internal PR, trusted-branch `push`, or `workflow_dispatch`. |
-| No default/base branch exists | Create an initial empty commit on the intended default branch before trying to verify a PR-triggered workflow. |
-| Script fails reading dataset fields | Re-inspect the dataset items with the Langfuse CLI, check `input`, `expected_output`, and metadata, and extract fields from object-shaped outputs explicitly. |

package/template/.agents/skills/integrations/langfuse/references/cli.md

@@ -1,60 +0,0 @@
----
-name: langfuse-cli
-description: Langfuse CLI usage reference — install, resource/action discovery, credentials, and common usage tips for `langfuse-cli`. Use for further tips on using the Langfuse CLI.
-metadata:
-  required_access:
-    - LANGFUSE_PROJECT_INTERFACE
----
-
-# Langfuse CLI Reference
-
-Documentation: https://langfuse.com/docs/api-and-data-platform/features/cli
-
-## Install
-
-```bash
-# Run directly (recommended)
-npx langfuse-cli api <resource> <action>
-bunx langfuse-cli api <resource> <action>
-
-# Or install globally
-npm i -g langfuse-cli
-langfuse api <resource> <action>
-```
-
-## Discovery
-
-```bash
-# List all resources and auth info
-langfuse api __schema
-
-# List actions for a resource
-langfuse api <resource> --help
-
-# Show args/options for a specific action
-langfuse api <resource> <action> --help
-
-# Preview the curl command without executing
-langfuse api <resource> <action> --curl
-```
-
-## Credentials
-
-Set environment variables:
-
-```bash
-export LANGFUSE_PUBLIC_KEY=pk-lf-...
-export LANGFUSE_SECRET_KEY=sk-lf-...
-export LANGFUSE_BASE_URL=https://cloud.langfuse.com  
-```
-
-## Tips
-
-- Use `--json` for machine-readable JSON output
-- Use `--curl` to preview the HTTP request without executing
-- All list commands support filtering — check `<resource> <action> --help` for available options
-- Prefer `observations` over `legacy-observations-v1s` — `observations` is the modern high-performance endpoint (cursor pagination, selective field groups); `legacy-observations-v1s` is the deprecated v1
-- Prefer `metrics` over `legacy-metrics-v1s` for the same reason
-- Prefer `scores` over `legacy-score-v1s` for list/get operations
-- Always query via `observations`, not `traces`, even when the user phrases the request in terms of traces — the `traces` endpoints are outdated (add `--trace-id` to scope to a known trace). See the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) for the v1 → v2 mapping.
-- Pagination: legacy v1 endpoints use `--limit` and `--page`; modern endpoints (`observations`, `metrics`, `scores`) use cursor-based pagination — pass `--limit`, then thread `meta.cursor` from the response into the next request's `--cursor`

package/template/.agents/skills/integrations/langfuse/references/create-dataset.md

@@ -1,35 +0,0 @@
----
-name: langfuse-dataset-construction
-description: Collaborative Langfuse dataset creation workflow. Use when the user needs to create, design, seed, reshape, review, or upload a Langfuse dataset or dataset version; especially when they need a minimal but complete dataset, e.g. for quality checks or avoiding regression.
-metadata:
-  required_access:
-    - LANGFUSE_PROJECT_INTERFACE
-    - LANGFUSE_PROJECT_SCRIPT
----
-
-# Langfuse Dataset Construction
-
-## Primary Guide
-
-Follow the [Langfuse Academy datasets guide](https://langfuse.com/academy/datasets) as the human-readable source of truth for dataset design; fetch current docs before implementation.
-
-Use CLI schema/help discovery for current Langfuse API mechanics.
-
-## Workflow
-
-Guide the user through dataset creation as an interview, proposal, approval, implementation loop:
-
-1. Read the primary guide and relevant current Langfuse docs.
-2. Clarify the problem the user is facing, interviewing them if context is thin, to decide the goal, release, or evaluation decision the dataset should support.
-3. Inspect available context: the user's goal, the application path or codebase when available, existing datasets, traces, prompts, scores, monitors, user feedback, tickets, expert examples, existing eval and dataset assets.
-4. Interview the user on available sources beyond production traces.
-5. For each step going forward, propose a direction and get the user's approval, specifically:
-   - Dataset distribution dimensions (propose and get user input).
-   - Item schema: input, expected output, metadata (propose and get user input).
-6. Generate the first minimal draft of items against the approved schema and distribution, then present it for approval.
-7. Heavily prompt the user to review expected outputs, as AI-generated expected outputs cannot be considered ground truth. Send a link with instructions to review.
-
-## Critical Rules
-- Do not create, upsert, reshape, or upload a live Langfuse dataset until the user has approved the dataset goal, source mix, item schema, and first minimal draft, unless the user already gave those details and explicitly asked for immediate mutation.
-- Design the smallest complete dataset version that can serve the goal. Prefer a minimal reviewable v0 over broad coverage. A first draft is usually 5-12 high-signal items unless the user asks for a different size.
-- Keep `input`, `expectedOutput`, and `metadata` responsibilities separate. Put additional information, notes, and comments into `metadata`, not into `input` or `expectedOutput`.

package/template/.agents/skills/integrations/langfuse/references/error-analysis.md

@@ -1,87 +0,0 @@
----
-name: langfuse-error-analysis
-description: Deep-dive error analysis of an LLM pipeline or AI application using Langfuse traces.
-  Use this skill whenever the user wants to understand why their AI system is producing
-  bad outputs, where their pipeline is failing, or how to categorise and label failures
-  into a taxonomy and decide what to prioritise fixing. Also trigger for "review my
-  traces", "my outputs look wrong", "help me debug my LLM app", "I want to analyse
-  errors", "build a failure taxonomy", or "what's going wrong with my pipeline".
-metadata:
-  required_access:
-    - LANGFUSE_PROJECT_INTERFACE
----
-
-# Error Analysis
-
-## Primary Guide
-
-**1. Fetch the guide in this blogpost**
-
-https://langfuse.com/guides/cookbook/error-analysis-llm-applications.md
-
-If fetch is not available query for langfuse.com error analysis guide
-
-Read it in full. It defines the authoritative 5-step process (sample selection → open coding → clustering → labelling → deciding what to fix).
-
-**2. Guide the user through this step by step**
-
-You as a coding agent and the user go through this together to perform a full error analysis with their data in Langfuse. Set up the scores, representative sample, and annotation queue for the user, and provide direct UI links wherever their action is required. Be proactive and explain what is happening in plain language without reciting internal step numbers or jargon.
-
-## Rules CRITICAL
-- Perform interactions with the user's Langfuse instance yourself rather than telling the user to do them.
-- The user performs the open-coding review and supplies human labels; do not do this on their behalf.
-- Where a step needs the user's judgment or input, pause and ask before acting.
-- Use charts where possible to display data.
-
----
-
-## Langfuse Implementation Notes
-
-The guide describes the process. These notes cover the Langfuse-specific mechanics required to execute it.
-
-### Credentials
-
-Make sure Langfuse credentials are available before starting — a public key (`pk-lf-...`), a secret key (`sk-lf-...`), and the host (e.g. `https://cloud.langfuse.com` for EU, `https://us.cloud.langfuse.com` for US, `https://jp.cloud.langfuse.com` for JP, or a self-hosted URL). If they aren't configured, ask the user to set them — do not ask them to paste secret values into chat.
-
-Verify you can actually reach the user's project before proceeding. If access fails, stop and ask the user to check their credentials and host.
-
-### Annotation target: OBSERVATION versus TRACE
-
-> **CRITICAL:** In OpenTelemetry-instrumented apps, trace-level `input`/`output` can be null — content often lives in a GENERATION observation. In that case, add the GENERATION observation (not the trace) to the annotation queue, so the content being reviewed is actually visible.
-
-### Annotation queues
-
-> **CRITICAL:** Queues cannot be updated or deleted after creation. Create score configs first, then the queue with all config IDs. To add new configs later, create a new queue.
-
-
-**Always give the user a direct link immediately after creating a queue:**
-
-| Host | URL pattern |
-|------|-------------|
-| EU cloud | `https://cloud.langfuse.com/project/<projectId>/annotation-queues/<queueId>` |
-| US cloud | `https://us.cloud.langfuse.com/project/<projectId>/annotation-queues/<queueId>` |
-| Self-hosted | `<LANGFUSE_BASE_URL>/project/<projectId>/annotation-queues/<queueId>` |
-
-Instruction to give: *"Please open code the first ~50 examples. For each trace, write what you observe in the `open_coding` field (describe behaviour, don't diagnose root causes), then set `pass_fail_assessment` to Pass or Fail."*
-
-
-### Prompt fixes
-
-When a category warrants a prompt fix, always offer the user two options:
-1. Create it as a versioned prompt in Langfuse (tracked, usable via the prompt API)
-2. Draft the specific text change for them to review and apply
-
-### Setup evaluators
-
-When a category warrants an evaluator, build it following `references/setting-up-evals.md`.
-
-
-### Common gotchas
-
-| Mistake | Fix |
-|---------|-----|
-| Annotating the trace instead of the observation | Target the GENERATION observation, not the trace, when content lives there |
-| Creating a score config without checking existing ones | Check existing score configs first; they can't be deleted |
-| Queue created before score configs | Create configs → collect IDs → create queue |
-| Requesting too many traces at once | Page size is capped (max 100); paginate to get more |
-| No rate limiting on bulk queue item creation | Space out requests to avoid hitting rate limits (429) |

package/template/.agents/skills/integrations/langfuse/references/instrumentation.md

@@ -1,121 +0,0 @@
----
-name: langfuse-observability
-description: Instrument LLM applications with Langfuse tracing. Use when setting up Langfuse, adding observability to LLM calls, or auditing existing instrumentation.
-metadata:
-  required_access:
-    - CODEBASE
-    - LANGFUSE_PROJECT_SCRIPT
----
-
-# Langfuse Observability
-
-Instrument LLM applications with Langfuse tracing, following best practices and tailored to your use case.
-
-## Workflow
-
-### 1. Assess Current State
-
-Check the project:
-
-- Is Langfuse SDK installed?
-- What LLM frameworks are used? (OpenAI SDK, LangChain, LlamaIndex, Vercel AI SDK, etc.)
-- Is there existing instrumentation?
-
-**No integration yet:** Set up Langfuse using a framework integration if available. Integrations capture more context automatically and require less code than manual instrumentation.
-
-**Integration exists:** Audit against baseline requirements below.
-
-### 2. Verify Baseline Requirements
-
-Every trace should have these fundamentals:
-
-| Requirement               | Check                                                                                    | Why                                                    |
-| ------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| Model name                | Is the LLM model captured?                                                               | Enables model comparison and filtering                 |
-| Token usage               | Are input/output tokens tracked?                                                         | Enables automatic cost calculation                     |
-| Good trace names          | Are names descriptive? (`chat-response`, not `trace-1`)                                  | Makes traces findable and filterable                   |
-| Span hierarchy            | Are multi-step operations nested properly?                                               | Shows which step is slow or failing                    |
-| Correct observation types | Are generations marked as generations, and is each other call given its most specific type (`retriever` for a lookup, `agent` for a subagent, etc.) rather than a generic `tool`/`span`? See the [observation types docs](https://langfuse.com/docs/observability/features/observation-types). | Enables model-specific analytics and drives the Agent Graph |
-| Sensitive data masked     | Is PII/confidential data excluded or masked?                                             | Prevents data leakage                                  |
-| Trace input/output        | Does the trace capture meaningful input/output? Is input explicitly set to show only relevant data (e.g., user message), not all function args? | Makes traces readable in the UI and avoids leaking sensitive args |
-
-Framework integrations (OpenAI, LangChain, etc.) handle model name, tokens, and observation types automatically. Prefer integrations over manual instrumentation.
-
-Docs: https://langfuse.com/docs/tracing
-
-**Beyond the baseline**, add context relevant to the app. Infer from code where possible; only ask when it's not obvious (e.g. how they judge a good vs. bad response, what they'd filter a dashboard by, which user segments they'd compare). These are not baseline — add only what fits.
-
-| If code shows...                                     | Add                 | Why                                                                             |
-| ---------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------- |
-| Conversation history, chat endpoints, message arrays | `session_id`        | Groups conversations — [docs](https://langfuse.com/docs/tracing-features/sessions) |
-| User authentication, `user_id` variables             | `user_id`           | User filtering and cost attribution — [docs](https://langfuse.com/docs/tracing-features/users) |
-| Multiple distinct endpoints/features                 | `feature` tag       | Per-feature analytics — [docs](https://langfuse.com/docs/tracing-features/tags) |
-| Customer/tenant identifiers                          | `customer_tier` tag | Cost/quality breakdown by segment — [docs](https://langfuse.com/docs/tracing-features/tags) |
-| Feedback collection, ratings                         | Feedback score      | Quality filtering and trends — [docs](https://langfuse.com/docs/scores/overview) |
-
-### 3. Run and Self-Audit the Traces (required)
-
-Instrumentation isn't done when the code compiles. This is a loop you own as the agent, it's your responsibility to deliver traces of the highest quality your can produce:
-
-**a.** Execute the instrumented path end-to-end so a trace is actually sent.
-
-**b.** Fetch the trace(s) you just created from Langfuse. Any method works (`langfuse-cli`, REST API, SDK, MCP); the CLI is usually simplest — see [references/cli.md](references/cli.md).
-
-**c.** Audit the trace against the best-practices page. **Always fetch it fresh — never audit from memory, this cannot be skipped** (the guidance changes over time):
-
-https://langfuse.com/docs/observability/best-practices
-
-Ask yourself, for each observation: is all data that a user might need in the future, to understand exactly what context the agent had when it made decisions, available in Langfuse?
-
-**d.** Fix every gap you find, then re-run and re-fetch to confirm. Repeat until the trace clears the guidance. Then report what you audited and changed, and link the final trace.
-
-### 4. Explore Traces With the User
-
-With a clean trace in place, invite the user to explore it in the Langfuse UI:
-
-"Your traces are now appearing in Langfuse. Take a look at a few of them—see what data is being captured, what's useful, and what's missing."
-
-Point them to the relevant views:
-
-- Traces view: individual requests
-- Sessions view: grouped conversations (if `session_id` added)
-- Dashboard: filtered views using tags
-- Scores: filter by quality metrics
-
-This helps them understand what they're getting, spot what's missing, and ask better questions about what to add next.
-
-## Always Explain Why
-
-When suggesting additions, explain the user benefit:
-
-```
-"I recommend adding session_id to your traces.
-
-Why: This groups messages from the same conversation together.
-You'll be able to see full conversation flows in the Sessions view,
-making it much easier to debug multi-turn interactions.
-
-Learn more: https://langfuse.com/docs/tracing-features/sessions"
-```
-
-## Multi-agent systems (subagent dispatch)
-
-When one agent's execution dispatches OTHER agents (coding agents like Claude Code/Codex, research agents, orchestrator/worker architectures), a few extra points on top of the baseline:
-
-- **Type a subagent's own execution as `agent`, not `tool`/`span`.** A bare tool/span for a dispatch hides all of the subagent's internal structure; `agent` lets it show up as its own node in the [Agent Graph](https://langfuse.com/docs/observability/features/agent-graphs).
-- **Don't emit duplicate dispatch + execution nodes.** Emitting both a `tool`-typed "dispatch" span and a separate `agent`-typed observation for the same subagent, as siblings, double-represents one event. Emit only the `agent` observation when you have the subagent's actual execution; keep a bare tool span only as a fallback when you have no visibility into what the subagent did.
-- **Nest recursively.** Nest the subagent's `agent` observation under the `agent` or `span` that orchestrates the dispatch, as a sibling of the `generation` that requested it. Within the subagent, put its generations, tool calls, and nested subagent executions under that subagent's `agent` observation; each tool or nested subagent is a sibling of the generation that requested it, not a child of that generation.
-- **Name subagents distinctly.** Frameworks often default every subagent to the same generic role name, making them indistinguishable in the tree and graph (nodes key on name). Derive a specific name from the subagent's actual task/role when the framework doesn't provide one.
-
-## Common Mistakes
-
-| Mistake                                        | Problem                                             | Fix                                                                               |
-| ---------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
-| No `flush()` in scripts                        | Traces never sent                                   | Call `langfuse.flush()` before exit                                               |
-| Flat traces                                    | Can't see which step failed                         | Use nested spans for distinct steps                                               |
-| Generic trace names                            | Hard to filter                                      | Use descriptive names: `chat-response`, `doc-summary`                             |
-| Logging sensitive data                         | Data leakage risk                                   | Mask PII before tracing                                                           |
-| Not explicitly setting input with `@observe`   | All function args become trace input (including API keys, configs) | Python: use `langfuse.update_current_span(input=...)`. JS/TS: use `updateActiveObservation({ input: ... })`. Set only the relevant input (e.g., user message) |
-| Manual instrumentation when integration exists | More code, less context                             | Use framework integration                                                         |
-| Langfuse import before env vars loaded         | Langfuse initializes with missing/wrong credentials | Import Langfuse AFTER loading environment variables (e.g., after `load_dotenv()`) |
-| Wrong import order with OpenAI                 | Langfuse can't patch the OpenAI client              | Import Langfuse and call its setup BEFORE importing OpenAI client                 |