quiver-cli 1.2.0 → 1.3.1

package/template/.agents/skills/design/shadcn/rules/chat.md

@@ -208,6 +208,32 @@ write a `useStickToBottom` hook, a `ResizeObserver`, or manual `scrollTop` math.
   and scrolls back on click. `direction="end"` (default) or `direction="start"`.
   It is a self-managing control, so don't gate it behind your own scroll-position
   state.
+- **Open a saved transcript without a flash.** `defaultScrollPosition` applies
+  after mount. When it is `"end"` or `"last-anchor"`, the viewport has
+  `data-pending-scroll` until that position is applied. The styled viewport
+  hides. For `"end"` on first paint when messages are in the server HTML, copy
+  this script into the page, not into the primitive. Skip it for `"last-anchor"`
+  and for client-fetched messages. Keep `suppressHydrationWarning` on the
+  viewport. Pass a `nonce` if you use a Content Security Policy.
+
+```tsx
+const scrollToEndScript = `(function () {
+  var viewport = document.getElementById("messages")
+  if (!viewport) {
+    return
+  }
+  viewport.scrollTop = viewport.scrollHeight
+  viewport.removeAttribute("data-pending-scroll")
+})()`
+
+<MessageScroller>
+  <MessageScrollerViewport id="messages" suppressHydrationWarning>
+    <MessageScrollerContent>{/* transcript */}</MessageScrollerContent>
+  </MessageScrollerViewport>
+  <script dangerouslySetInnerHTML={{ __html: scrollToEndScript }} />
+  <MessageScrollerButton />
+</MessageScroller>
+```
 
 For a "thinking…" indicator while the model generates, apply the `shimmer`
 utility to text. Don't author a custom keyframe animation. See

package/template/.agents/skills/hono/SKILL.md

@@ -5,7 +5,15 @@ description: Use when building Hono web applications or when the user asks about
 
 # Hono Skill
 
-Build Hono web applications. This skill provides inline API knowledge for AI. Use `npx hono request` to test endpoints. If the `hono-docs` MCP server is configured, prefer its tools for the latest documentation over the inline reference.
+Build Hono web applications. This skill provides inline API knowledge for AI. Use `npx hono request` to test endpoints.
+
+## Latest Documentation
+
+For details beyond this inline reference, fetch the latest documentation from https://hono.dev. Get the index of doc pages from `https://hono.dev/llms.txt`, then fetch a page with the `Accept: text/markdown` header to receive it as Markdown:
+
+```bash
+curl -H "Accept: text/markdown" https://hono.dev/docs/helpers/cookie
+```
 
 ## Hono CLI Usage
 
@@ -231,11 +239,17 @@ import { timing } from 'hono/timing'
 import { cache } from 'hono/cache'
 import { bearerAuth } from 'hono/bearer-auth'
 import { jwt } from 'hono/jwt'
+import { jwk } from 'hono/jwk'
 import { csrf } from 'hono/csrf'
 import { ipRestriction } from 'hono/ip-restriction'
 import { bodyLimit } from 'hono/body-limit'
+import { timeout } from 'hono/timeout'
 import { requestId } from 'hono/request-id'
 import { methodOverride } from 'hono/method-override'
+import { methodNotAllowed } from 'hono/method-not-allowed'
+import { languageDetector } from 'hono/language'
+import { some, every, except } from 'hono/combine'
+import { contextStorage, getContext } from 'hono/context-storage'
 import { trailingSlash, trimTrailingSlash } from 'hono/trailing-slash'
 
 // Registration
@@ -372,7 +386,7 @@ app.get('/', (c) => {
 
 ### jsxRenderer Middleware
 
-Use `jsxRenderer` middleware for layouts. See `npx hono docs /docs/middleware/builtin/jsx-renderer` for details.
+Use `jsxRenderer` middleware for layouts. For details, see https://hono.dev/docs/middleware/builtin/jsx-renderer
 
 ### Async Components
 
@@ -529,7 +543,7 @@ import { upgradeWebSocket } from 'hono/cloudflare-workers' // or other adapter
 
 Available helpers: Accepts, Adapter, ConnInfo, Cookie, css, Dev, Factory, html, JWT, Proxy, Route, SSG, Streaming, Testing, WebSocket.
 
-For details, use `npx hono docs /docs/helpers/<helper-name>`.
+For details, see `https://hono.dev/docs/helpers/<helper-name>` (fetch with `Accept: text/markdown`).
 
 ### Factory
 

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

@@ -1,6 +1,7 @@
 ---
 name: langfuse
-description: Interact with Langfuse and access its documentation. Use when needing to (1) query or modify Langfuse data programmatically via the CLI — traces, prompts, datasets, scores, sessions, and any other API resource, (2) look up Langfuse documentation, concepts, integration guides, or SDK usage, or (3) understand how any Langfuse feature works. This skill covers CLI-based API access (via npx) and multiple documentation retrieval methods.
+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/*)
@@ -24,7 +25,7 @@ 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**: Check the relevant reference file below for use-case-specific guidelines before implementing
+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.
 
@@ -32,14 +33,17 @@ Follow these principles for ALL Langfuse work:
 ## 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 an application and Langfuse project for the v4 platform migration: references/v4-project-migration.md
+- 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 — reading traces, building failure taxonomy, deciding what to fix: references/error-analysis.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
 

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

@@ -56,5 +56,5 @@ export LANGFUSE_BASE_URL=https://cloud.langfuse.com
 - 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
-- For broad trace queries, `traces list` can time out on Langfuse Cloud — use `observations list` (with `--trace-id` if you're traversing from a known trace) instead. See the [Observations API docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) for the v1 → v2 mapping.
+- 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

@@ -0,0 +1,35 @@
+---
+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

@@ -2,12 +2,10 @@
 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, how to categorise or label failures,
-  what to prioritise fixing, or how to set up evaluators. Also trigger for "review my
+  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", "what's going wrong with my pipeline", or any
-  request to systematically inspect, annotate, or score Langfuse traces. If the user
-  is trying to understand or improve the quality of an AI system's outputs, use this skill.
+  errors", "build a failure taxonomy", or "what's going wrong with my pipeline".
 metadata:
   required_access:
     - LANGFUSE_PROJECT_INTERFACE
@@ -27,12 +25,13 @@ Read it in full. It defines the authoritative 5-step process (sample selection
 
 **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. Do as much of the work as you can directly for the user (look up traces, create annotation queues, ...). Provide them with direct links to UI wherever their action is required. Be proactive and narrate what is going on for the user. 
+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 — don't say "now do this in Langfuse" when you can do it directly
-But don't barrel through on assumptions: where a step needs the user's judgment or input (e.g. what to fix, how to label, which evaluator), pause and ask before acting
-Use charts where possible to display data
+- 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.
 
 ---
 
@@ -74,7 +73,7 @@ When a category warrants a prompt fix, always offer the user two options:
 
 ### Setup evaluators
 
-When a category warrants an evaluator setup, propose the type of evaluator and offer to set it up for the user
+When a category warrants an evaluator, build it following `references/setting-up-evals.md`.
 
 
 ### Common gotchas

package/template/.agents/skills/integrations/langfuse/references/judge-calibration.md

@@ -192,8 +192,10 @@ Before trusting the judge on production traffic:
 3. **Metric recomputation check**: recompute aggregate stats from row-level
    flags and compare.
 4. **TPR/TNR review**: inspect both directions for class-direction bias.
-5. **Threshold**: target `TPR > 0.90` and `TNR > 0.90` before high-stakes
-   automation.
+5. **Acceptance criteria**: before the held-out test, agree on thresholds for
+   the relevant metrics based on the costs of false positives and false
+   negatives and whether the judge informs monitoring or automation. Do not
+   infer "ship" from a universal cutoff.
 
 ## 7) Report format
 
@@ -223,10 +225,10 @@ scores to the experiment traces and run-level scores to the dataset run.
 Use manual REST score creation only as a fallback when not using the SDK
 experiment runner, or for local smoke tests. See
 [Scores via SDK](https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk)
-and the [Scores API reference](https://langfuse.com/docs/api) (`POST /api/public/scores`)
-for the current payload shape. Do not use the current `langfuse-cli` score-create
-wrapper unless `--help` shows a usable `value` argument; `langfuse-cli@0.0.10`
-exposes `legacy-score-v1s create` but cannot pass the required score `value`.
+and the [Scores API reference](https://langfuse.com/docs/api) for the current
+payload shape. Before using the CLI for score creation, inspect its current
+schema and action help instead of assuming resource names, arguments, or
+capabilities from a known package version.
 
 Score names to emit:
 

package/template/.agents/skills/integrations/langfuse/references/sdk-upgrade.md

@@ -0,0 +1,34 @@
+---
+name: langfuse-sdk-upgrade
+description: Upgrade Langfuse SDKs and application instrumentation while preserving trace attributes across observations. Use for Python or JS/TS SDK migrations, including the application side of a v4 platform migration.
+metadata:
+  required_access:
+    - CODEBASE
+    - LANGFUSE_PROJECT_SCRIPT
+---
+
+# Langfuse SDK upgrade
+
+## Sources of truth
+
+Determine every installed Langfuse SDK major version, then fetch each applicable leaf guide in full before editing:
+
+- [SDK upgrade paths](https://langfuse.com/docs/observability/sdk/upgrade-path)
+- [Python v3 to v4](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4)
+- [JS/TS v4 to v5](https://langfuse.com/docs/observability/sdk/upgrade-path/js-v4-to-v5)
+- [Instrumentation and attribute propagation](https://langfuse.com/docs/observability/sdk/instrumentation#add-attributes)
+- [Sessions and session-level metrics](https://langfuse.com/docs/observability/features/sessions)
+- [Direct OpenTelemetry ingestion](https://langfuse.com/integrations/native/opentelemetry)
+
+Follow every intermediate guide when the installed version is more than one major behind. Use the current docs for implementation details; do not copy examples from this file.
+
+## Workflow
+
+1. Inventory every SDK, integration package, direct OpenTelemetry exporter, initialization site, instrumentation wrapper, lockfile, worker, script, and test that can emit Langfuse data.
+2. Find every source of correlating attributes, including `session_id`/`sessionId`, `user_id`/`userId`, tags, metadata, version, environment, and trace name. Search for the values and surrounding application concepts, not only removed SDK method names.
+3. Apply every relevant item from the exact version-specific guides. Preserve each correlating attribute by establishing its documented propagation scope before any observation-producing call that must inherit it.
+
+
+## Completion report
+
+Report the versions before and after, changed instrumentation paths, attribute sources and propagation scopes, validation performed, inspected trace or session, and any remaining blocked verification.

package/template/.agents/skills/integrations/langfuse/references/setting-up-evals.md

@@ -0,0 +1,65 @@
+---
+name: langfuse-setting-up-evals
+description: Set up evaluation by finding gaps across signal capture, monitoring, and evaluator metrics, then addressing the right one first.
+metadata:
+  required_access:
+    - LANGFUSE_PROJECT_INTERFACE
+---
+
+# Setting up evals
+
+- **Act as executor and teacher.** Do the work and, above all, explain why the approach fits the user's goal and data.
+- **Teach decision-making, not configuration.** Explain the reasoning, tradeoffs, and limitations—not sampling rates, targets, score types, or other setup details. The response must leave the user able to repeat or change the approach and make future decisions without you.
+
+Always read [Choosing what to evaluate](https://langfuse.com/academy/evaluate/choosing-what-to-evaluate) and [Evaluation](https://langfuse.com/academy/evaluate). Use their guidance to interpret their project, but do not return it as a generic setup plan.
+
+If the user has a precise metric, skip to **Build the evaluator**. Otherwise, do not assume that choosing evaluator metrics is the next step.
+
+## Find the measurement gap
+
+Before advising:
+
+- Inspect enough representative traces to present concrete findings of your own before asking about metrics.
+- Inventory existing datasets, evaluators, traces, etc. as context; do not assume they should be reused or represent a current priority. Treat their importance as unconfirmed until the user agrees.
+- Identify what is already surfaced through trace errors, logged data, existing scores, or other monitoring; what is available but not monitored; what important user or product signals are not captured; and what genuinely requires an evaluator.
+- Do not ask the user for information you can inspect.
+- If project access is unavailable, say so instead of substituting a generic plan.
+
+Do not add an evaluator that duplicates an existing error or logged signal. For example, do not evaluate valid JSON when invalid JSON already produces a trace error.
+
+Treat trace errors and logged failures as existing coverage. Unless the user wants operational monitoring, do not let them displace the search for subtler qualitative signals that are not yet captured. Do not propose alerts, paging, or release gates before asking how the measurement should be used.
+
+Do not propose evaluating a known failure with an owner and a planned one-time fix unless the user wants to track whether it recurs.
+
+If formal error analysis is the right next step, explain why and ask whether the user wants to do it. If they agree, run it following `references/error-analysis.md`, and do not start metric selection until the analysis is complete.
+
+## Define the metric set
+
+Existing project materials inform the questions you'll ask; it does not determine what the user values.
+
+When forming tentative recommendations:
+
+- Start with direct evidence of user or product outcomes, recurring failures visible in traces or user reactions, and important signals the application is not yet capturing.
+- Prefer quick wins: signals that are application-specific, actionable, reasonably reliable to start measuring. A good example signal is user (dis)satisfaction.
+- Recommend metrics only for problems evidenced in current data. A behavior being common or theoretically risky is not a reason to run an evaluator.
+- For live evaluation, recommend only metrics that can be scored from the available live data without ground truth; never suggest a metric that requires knowing the correct answer, expected outcome, or ideal resolution.
+- Do not propose generic starting metrics such as `helpfulness`, `quality`, `relevance`, `hallucination`, `groundedness`, `task completion`, `task success`, or `reliability`.
+- Before presenting any metric, verify that it can actually be measured using the available data and Langfuse's supported evaluator inputs. If not, identify what must be captured instead.
+- Explain why each recommendation deserves attention before the alternatives, then ask the user whether that priority matches their goals.
+
+When specific failures or hard requirements are known and metric selection is the next task, ask focused, dependent questions about which ones matter and what decisions their measurement should support. Give a recommendation grounded in the project, leave the decision to the user, and wait for their answer.
+
+Do not treat any metric as selected, choose evaluator types, ask implementation questions, or implement anything until the user has answered and explicitly confirmed the metric set.
+
+## Build the evaluator
+
+For evaluator functionality, use the unstable API endpoints.
+
+Follow [Writing good evaluators](https://langfuse.com/academy/evaluate/writing-evaluators) to choose the evaluator type; do not always default to an LLM-as-a-judge.
+
+- Before creating the evaluator, verify its target filter by fetching the observations it actually matches. Confirm the set is exactly what you intend—no duplicates that would be scored (and billed) twice.
+- Prioritize a clean score name: it is the metric that lands on every observation, so name it after what is measured (`refusal`), not after the evaluator (`refusal judge`). Keep any evaluator-mechanism wording out of the score name.
+- Explain why the chosen evaluation method measures the intended behavior, what evidence it relies on, what it cannot tell the user, and when another method would be better.
+- When methods have significant trade-offs and none is clearly superior, explain the options and let the user decide before implementation.
+- Only if an LLM-as-a-judge is the best fit, calibrate it on real examples before treating it as ready(`references/judge-calibration.md`). You can do this by running an experiment on a dataset where the prompt being tested is the LLM-as-a-judge prompt.
+- Share a link to the evaluator.

package/template/.agents/skills/integrations/langfuse/references/skill-feedback.md

@@ -1,55 +1,35 @@
 ---
 name: langfuse-skill-feedback
-description: Submit feedback about the Langfuse skill to its maintainers via GitHub Discussions. Use when the user indicates the skill gave incorrect guidance, is missing information, or could be improved.
+description: Submit feedback about the Langfuse skill to its maintainers. Use when the skill's instructions are wrong, outdated, missing something, or could be improved.
 metadata:
   required_access:
-    - GITHUB
+    - LANGFUSE_PROJECT_INTERFACE
 ---
 
 # Skill Feedback
 
-Follow these steps exactly:
+Use this only for feedback about the skill itself, not Langfuse the product or a user's application data.
 
-1. **Ask permission**: Ask the user if they'd like you to submit feedback to the skill maintainers. Make it clear this is about the skill (the agent instructions), not about Langfuse the product. If they decline, move on.
-2. **Draft feedback**: Write the feedback using the form structure below. Present the draft to the user and ask if they'd like to change anything before submitting.
-3. **Submit**: Once approved, submit via `gh` CLI as described below. Share the resulting discussion URL with the user.
+1. Draft concise feedback using the following structure:
+  - **Describe your idea or feedback** (required)
+    A clear description of what went wrong or what could be improved. Include:
+    - What the user was trying to do (as `goal`)
+    - What the skill did vs what was expected
+    - Any specific instructions that were incorrect or missing
 
-## Feedback Form Structure
+  - **What would the ideal outcome look like?** (optional)
+    What the correct behavior or guidance should be.
 
-Draft the feedback using these two fields:
+  If feedback targets existing skill, reference in `target`.
+2. If the user wants a reply, ask them to include an email address in `feedback`; use only an address they explicitly provide.
+3. Show every submitted field exactly as it will be sent and ask for explicit permission. Do not submit without approval.
 
-**Describe your idea or feedback** (required)
-A clear description of what went wrong or what could be improved. Include:
-- What the user was trying to do
-- What the skill did vs what was expected
-- Any specific instructions that were incorrect or missing
+## Submission options
 
-**What would the ideal outcome look like?** (optional)
-What the correct behavior or guidance should be.
+Use the first available option, or the option the user prefers:
 
-Format the body as markdown with the two field labels as headings.
+1. **Authenticated Langfuse MCP, CLI, or Public API** — prefer the `submitFeedback` tool on the Langfuse MCP server. If it is unavailable, discover the current feedback operation with the Langfuse CLI schema/help and submit through the authenticated Public API. Do not ask users to paste credentials into chat.
+2. **Langfuse Docs MCP** — use its unauthenticated `submitFeedback` tool when no authenticated Langfuse interface is available.
+3. **GitHub issue or discussion** — if no MCP/CLI/API is available, or the user wants a public, trackable thread, provide a prefilled discussion link for the user to submit: `https://github.com/langfuse/skills/discussions/new?category=ideas-improvements&title=<url-encoded title>&body=<url-encoded body>`. Use `https://github.com/langfuse/skills/issues/new` if they prefer an issue.
 
-## Submitting
-
-Create a GitHub Discussion on the `langfuse/skills` repository using the GraphQL API:
-
-```bash
-gh api graphql -f query='
-mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
-  createDiscussion(input: {repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body}) {
-    discussion { url }
-  }
-}' \
-  -f repoId="$(gh api graphql -f query='{ repository(owner: "langfuse", name: "skills") { id } }' --jq '.data.repository.id')" \
-  -f categoryId="$(gh api graphql -f query='{ repository(owner: "langfuse", name: "skills") { discussionCategories(first: 10) { nodes { id name } } } }' --jq '.data.repository.discussionCategories.nodes[] | select(.name == "Ideas & Improvements") | .id')" \
-  -f title="<concise title>" \
-  -f body="<formatted feedback>"
-```
-
-If the `gh` CLI is not authenticated or the request fails, give the user this link to create the discussion manually:
-
-```
-https://github.com/langfuse/skills/discussions/new?category=ideas-improvements
-```
-
-After submission, share the discussion URL with the user.
+Report the Langfuse correlation ID or GitHub URL. If submission fails, give a safe error without exposing credentials or request bodies.

package/template/.agents/skills/integrations/langfuse/references/user-feedback.md

@@ -45,37 +45,11 @@ Rules:
 
 ### 3. Implement Score Creation
 
-**For implicit feedback (server-side):** Use `langfuse.create_score()` / `langfuse.score.create()` wherever the event is already handled in application code. Fetch SDK docs for current API: https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk
+Fetch and follow the current [user feedback guide](https://langfuse.com/docs/observability/features/user-feedback) and [score ingestion docs](https://langfuse.com/docs/evaluation/evaluation-methods/scores-via-sdk) before editing code. They contain the current browser and server SDK APIs plus framework-specific patterns for returning trace IDs to the frontend.
 
-**For explicit feedback (frontend):** Use `LangfuseWeb` in the browser. It uses the public key only — no secret key exposed.
+**For implicit feedback (server-side):** Create the score where the behavior is already handled in application code.
 
-```typescript
-import { LangfuseWeb } from "langfuse";
-
-const langfuse = new LangfuseWeb({
-  publicKey: process.env.NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY!,
-  baseUrl: process.env.NEXT_PUBLIC_LANGFUSE_HOST,
-});
-
-langfuse.score({
-  traceId,
-  name: "user-thumbs",
-  value: 1, // 1 = positive, 0 = negative
-  dataType: "BOOLEAN",
-  comment: optionalUserComment,
-});
-```
-
-The trace ID must be available in the frontend for this to work. For Vercel AI SDK, the non-obvious pattern is using `generateMessageId`:
-
-```typescript
-import { getActiveTraceId } from "@langfuse/tracing";
-
-// Inside route handler wrapped with observe()
-return result.toUIMessageStreamResponse({
-  generateMessageId: () => getActiveTraceId() || crypto.randomUUID(),
-});
-```
+**For explicit feedback (frontend):** Make the relevant trace ID available to the frontend and use the current Langfuse browser SDK with a public key only. Never expose a Langfuse secret key in browser code.
 
 ### 4. Verify
 
@@ -87,6 +61,6 @@ Point users to what they can do with feedback data: filter traces by low scores,
 
 | Mistake | Problem | Fix |
 |---------|---------|-----|
-| Secret key in frontend code | Security risk | Use `LangfuseWeb` with public key only |
+| Secret key in frontend code | Security risk | Use the current browser SDK with a public key only |
 | Missing `dataType` on boolean scores | Value `1` inferred as `NUMERIC` | Always pass `dataType: "BOOLEAN"` explicitly |
 | Inconsistent score names across the app | Can't aggregate or filter reliably | Pick one name per feedback type, use it everywhere |

package/template/.agents/skills/integrations/langfuse/references/v4-project-migration.md

@@ -35,7 +35,8 @@ Discover unstable schemas before use.
 
 - Inventory every Langfuse SDK, integration, OTEL exporter, initialization site, lockfile, raw request, generated client, script, notebook, and CI call.
 - Upgrade to the latest stable SDK major required by the current docs and apply every applicable breaking change. Record both declared and resolved versions; update an existing lockfile.
-- Put overall input/output on the root observation and propagate every trace attribute needed to filter or aggregate observations.
+- Find every source of correlating attributes, including session and user IDs, tags, metadata, version, environment, and trace name; do not search only for removed SDK methods.
+- Put overall input/output on the root observation. Establish the documented propagation scope before observation-producing calls so every applicable child receives the attributes needed for filtering and aggregation, including the session ID on cost-bearing generations.
 - For raw `/api/public/ingestion`, use the current Langfuse SDK in Python or JS/TS. For other languages, use the language's native OpenTelemetry API and follow the custom-ingestion guide.
 - When replacing synchronous ingestion, assess buffering, retries, flushing, shutdown, and error propagation. Do not claim identical delivery semantics without verification.
 - For other deprecated APIs, migrate the path, parameters, pagination, filters, field groups, response parsing, and downstream consumer together using the deprecated-API guide.
@@ -68,6 +69,7 @@ Discover unstable schemas before use.
 
 - Test applicable hierarchy, root input/output, propagated attributes, public/release/environment behavior, API pagination and parsing, delivery semantics, and absence of deprecated calls.
 - Before production cutover, send representative traces from the migrated instrumentation to a non-production Langfuse project and inspect the resulting observations there. Mocked tests do not verify backend ingestion or project behavior.
+- On a session path, confirm the root and every applicable child observation carry the intended session ID and that session cost includes the cost-bearing children.
 - Re-read rules and integrations after writes. Preserve disabled legacy rules for rollback; never claim completion without checking the Evaluators UI on the target host for legacy rows.
 - The readiness report must contain exactly these seven rows, each marked `ready`, `changed`, `manual action`, or `blocked`: project access; SDK/instrumentation; trace evaluators; dataset evaluators; direct APIs; exports; verification/rollback.
 - In evaluator rows, separate contracts verified against project data from targets suggested only by code inspection. For every row not marked `ready`, include the blocker, next action, and a direct UI link when applicable.

package/template/.agents/skills/supabase/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.7](https://github.com/supabase/agent-skills/compare/v0.1.6...supabase-v0.1.7) (2026-08-12)
+
+
+### Features
+
+* **supabase:** add debugging workflows to the supabase skill ([#112](https://github.com/supabase/agent-skills/issues/112)) ([3a4f0ce](https://github.com/supabase/agent-skills/commit/3a4f0ce0782e0cbdcf187c362e8d15d9e324462b))
+
 ## [0.1.6](https://github.com/supabase/agent-skills/compare/v0.1.5...supabase-v0.1.6) (2026-07-30)
 
 

package/template/.agents/skills/supabase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase
-description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, declarative schemas, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector)."
+description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, declarative schemas, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector); debugging and troubleshooting errors or unexpected behavior on Supabase projects (HTTP errors, Postgres errors, RLS surprises, permission denied, schema cache issues, timeouts, Edge Function crashes, Realtime drops, Storage failures) and reading or querying logs (Logs Explorer, ClickHouse)."
 metadata:
   author: supabase
   version: "0.1.2"
@@ -139,6 +139,10 @@ Do NOT use `apply_migration` to change a local database schema — it writes a m
 3. **Generate the migration** → `supabase db pull <descriptive-name> --local --yes`
 4. **Verify** → `supabase migration list --local`
 
+## Debugging
+
+When you get an error on a Supabase-related request, for example an error code from the Supabase REST API, Postgres database, or PostgREST, an empty result, getting blocked by RLS unexpectedly, or an error from a Supabase service like Auth, Realtime, Edge Functions, or Storage, you **must** fetch Supabase's [Monitoring and Debugging](https://supabase.com/docs/guides/monitoring-and-debugging.md) documentation before diagnosing or proposing a fix, rather than working from memory. The same docs also cover performance optimizations, such as slow queries and missing indexes.
+
 ## Reference Guides
 
 - **Skill Feedback** → [references/skill-feedback.md](references/skill-feedback.md)

package/template/.agents/skills/writing/humanizer/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Siqi Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.