From fd0a669e1309f7a39095694000fad45b87545452 Mon Sep 17 00:00:00 2001
From: "releaser-ai-plugin[bot]"
 <273148615+releaser-ai-plugin[bot]@users.noreply.github.com>
Date: Fri, 4 Sep 2026 12:07:31 +0000
Subject: [PATCH] chore: sync skills (agent-skills-v0.880.0,
 context-mill@v1.51.0)

---
 .claude-plugin/marketplace.json               |  2 +-
 .claude-plugin/plugin.json                    |  2 +-
 .codex-plugin/plugin.json                     |  2 +-
 .cursor-plugin/plugin.json                    |  2 +-
 gemini-extension.json                         |  2 +-
 skills/creating-online-evaluations/SKILL.md   | 57 ++++++++-------
 .../references/evaluation-payload.md          | 16 ++--
 skills/inbox-exploration/SKILL.md             | 73 ++++++++++++++-----
 .../references/flutter.md                     |  2 +-
 .../references/web.md                         |  2 +-
 .../references/flutter.md                     |  2 +-
 .../references/web.md                         |  2 +-
 .../references/posthog-js.md                  |  4 +-
 .../references/anthropic.md                   |  6 ++
 .../references/azure-openai.md                |  6 ++
 .../references/cerebras.md                    |  6 ++
 .../references/cohere.md                      |  6 ++
 .../references/deepseek.md                    |  6 ++
 .../references/fireworks-ai.md                |  6 ++
 .../references/google.md                      |  6 ++
 .../references/groq.md                        |  6 ++
 .../references/helicone.md                    |  6 ++
 .../references/hugging-face.md                |  6 ++
 .../references/mistral.md                     |  6 ++
 .../references/ollama.md                      |  6 ++
 .../references/openai.md                      |  6 ++
 .../references/openrouter.md                  |  6 ++
 .../references/perplexity.md                  |  6 ++
 .../references/together-ai.md                 |  6 ++
 .../references/xai.md                         |  6 ++
 .../references/best-practices.md              |  2 +
 .../references/architecture.md                |  9 +++
 .../instrument-metrics/references/basics.md   |  2 +-
 .../references/start-here.md                  | 12 ++-
 skills/managing-experiment-lifecycle/SKILL.md | 11 +++
 skills/querying-posthog-data/SKILL.md         |  2 +-
 .../references/example-error-tracking.md      |  4 +-
 .../references/example-logs.md                |  2 +-
 .../references/example-session-replay.md      |  8 +-
 .../references/example-sessions.md            |  2 +-
 skills/resolving-ingestion-warnings/SKILL.md  | 12 +--
 skills/setting-up-data-catalog/SKILL.md       | 27 +++++--
 .../references/usage-type-routing.md          | 57 ++++++++-------
 43 files changed, 307 insertions(+), 113 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 2848573..7f0d66d 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -12,7 +12,7 @@
       "displayName": "PostHog",
       "source": "./",
       "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from your AI coding tool. Optionally capture Claude Code sessions to PostHog LLM Analytics.",
-      "version": "1.1.62",
+      "version": "1.1.63",
       "author": {
         "name": "PostHog",
         "email": "hey@posthog.com",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 5325958..9fcd8e8 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "posthog",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from your AI coding tool. Optionally capture Claude Code sessions to PostHog LLM Analytics.",
-  "version": "1.1.62",
+  "version": "1.1.63",
   "author": {
     "name": "PostHog",
     "email": "hey@posthog.com",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 6638b86..31d5083 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "posthog",
-  "version": "1.0.60",
+  "version": "1.0.61",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Codex",
   "author": {
     "name": "PostHog",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index a7c8457..40137c8 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "posthog",
   "displayName": "PostHog",
-  "version": "1.1.56",
+  "version": "1.1.57",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Cursor",
   "author": {
     "name": "PostHog",
diff --git a/gemini-extension.json b/gemini-extension.json
index cd26fe2..bd00d13 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
 {
   "name": "posthog",
-  "version": "1.0.58",
+  "version": "1.0.59",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Gemini CLI",
   "mcpServers": {
     "posthog": {
diff --git a/skills/creating-online-evaluations/SKILL.md b/skills/creating-online-evaluations/SKILL.md
index 3ed7862..51fbd86 100644
--- a/skills/creating-online-evaluations/SKILL.md
+++ b/skills/creating-online-evaluations/SKILL.md
@@ -2,15 +2,15 @@
 name: creating-online-evaluations
 description: >
   Author continuously-running online evaluations in PostHog AI observability, grounded in real failure
-  modes you've identified. Use when the user wants evaluations that automatically score new generations
-  or whole traces going forward — "create an eval to catch X", "continuously check that responses do Y",
+  modes you've identified. Use when the user wants evaluations that automatically score new generations or
+  whole traces going forward — "create an eval to catch X", "continuously check that responses do Y",
   "turn these failures into evals". Covers letting the explored data decide how many evals to create,
-  proposing that set in plain language and asking the user which ones they want, choosing the target and
-  eval type (hog / llm_judge / sentiment), configuring a provider, model, and usable provider key for an
-  llm_judge eval, scoping which generations trigger it via conditions, creating disabled, verifying scope,
-  and enabling. Falls back to proposing a sentiment eval when no failure mode is worth catching.
-  Finding and ranking the failure modes worth evaluating is its own job — use exploring-ai-failures first.
-  To debug or manage evaluations that already exist, use exploring-llm-evaluations.
+  proposing that set for the user to pick, choosing the target and eval type (hog / llm_judge /
+  sentiment), configuring a provider and model for an llm_judge eval (a provider key gates enabling, not
+  creation), scoping which generations trigger it via conditions, creating disabled, verifying scope, and
+  enabling. Proposes a sentiment eval when no failure mode is worth catching. Finding and ranking the
+  failure modes worth evaluating is its own job — use exploring-ai-failures first. To debug or manage
+  evaluations that already exist, use exploring-llm-evaluations.
 ---
 
 # Creating online evaluations
@@ -129,11 +129,11 @@ set into production, which is noise and (for a judge) cost the user didn't agree
 
 ### 2.1 — Choose the eval type
 
-| Use…        | When the criterion is…                                                                                                                |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `hog`       | Structural / rule-based (JSON parses, length, regex, tool-call shape). Cheap, deterministic, **no provider key needed.**              |
-| `llm_judge` | Subjective / fuzzy (tone, factuality, on-topic). Costs an LLM call per run; needs a provider, model, and usable provider key.         |
-| `sentiment` | You want sentiment labels on user messages, not a pass/fail (unless very specifically asked for, usually not relevant to this skill). |
+| Use…        | When the criterion is…                                                                                                                                                            |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hog`       | Structural / rule-based (JSON parses, length, regex, tool-call shape). Cheap, deterministic, **no provider key needed.**                                                          |
+| `llm_judge` | Subjective / fuzzy (tone, factuality, on-topic). Costs an LLM call per run; needs a provider and model. A usable provider key is only needed to enable it, not to create a draft. |
+| `sentiment` | You want sentiment labels on user messages, not a pass/fail (unless very specifically asked for, usually not relevant to this skill).                                             |
 
 Reach for `hog` first, escalate to `llm_judge` if there is no deterministic way to check for what we want to check.
 
@@ -210,12 +210,14 @@ when exact structure matters.
 
 ### 2.3 — Configure the LLM judge
 
-An `llm_judge` evaluation requires a valid `provider` and `model`. It also needs a usable provider key
-when it runs. `provider_key_id` controls whether the evaluation pins one specific key:
+An `llm_judge` evaluation requires only a valid `provider` and `model` to create as a draft. A usable
+provider key is needed to enable it, not to save it, so no `ok` key is a reason to keep the eval disabled,
+not a reason to stop. `provider_key_id` controls whether the evaluation pins one specific key:
 
 - Set `provider_key_id` to the UUID of an `ok`-state key for the same provider to pin it.
-- Set `provider_key_id` to `null` to use the team's active provider key. The active key must be in the
-  `ok` state and use the same provider as `model_configuration.provider`.
+- Set `provider_key_id` to `null` to use the team's active provider key. This is always a valid saved
+  value. To enable the eval, the active key must be in the `ok` state and use the same provider as
+  `model_configuration.provider`.
 
 Hog and sentiment evaluations skip this step.
 
@@ -229,10 +231,12 @@ Confirm the provider and model with `llma-evaluation-judge-models`.
 Call it with no arguments to see the whole catalog at once.
 Providers PostHog funds no models for come back empty unless you pass `key_id` for one of the team's keys; the response's `providers` list flags which ones those are.
 Prefer pinning the chosen key so a later team-wide active-key change does not change how the evaluation runs.
-Leave `provider_key_id` as `null` only after `llma-evaluation-config-get` confirms the active key is usable and its provider matches.
+Leave `provider_key_id` as `null` to run on the team's active key; before enabling, confirm with
+`llma-evaluation-config-get` that the active key is usable and its provider matches.
 
-If there is no usable key, you may still create a disabled draft for the user to review. Do not spot-run or
-enable it. Ask the user to add or validate a key in the UI before continuing.
+No usable key does not block creation. Create the disabled draft with a valid `provider` and `model` for
+the user to review. Do not spot-run or enable it, and ask the user to add or validate a key in the UI so it
+can be enabled later.
 
 ### 2.4 — Create it disabled
 
@@ -261,8 +265,9 @@ posthog:llma-evaluation-create
 ```
 
 For `llm_judge`, swap `evaluation_config` to `{ "prompt": "…" }` and add
-`"model_configuration": { "provider": "openai", "model": "gpt-5-mini", "provider_key_id": "<uuid of an ok-state key from llma-provider-key-list>" }`.
-Use `null` only when the active team key is `ok` and uses the same provider. Full field reference:
+`"model_configuration": { "provider": "openai", "model": "gpt-5-mini", "provider_key_id": null }`.
+Pin `provider_key_id` to the UUID of an `ok`-state key from `llma-provider-key-list` to run on one specific
+key; `null` runs on the team's active key. Either value saves a draft. Full field reference:
 [references/evaluation-payload.md](references/evaluation-payload.md).
 
 ### 2.5 — Verify the scope before enabling
@@ -283,7 +288,8 @@ For generation targets, `count()` is the run volume. For trace targets, count di
 `$ai_trace_id` values because matching generations from the same trace schedule only one run.
 
 If volume is high, set `rollout_percentage` below 100 to sample. Spot-check the evaluator with
-`llma-evaluation-test-hog` (hog) or `llma-evaluation-run` against one generation (llm_judge).
+`llma-evaluation-test-hog` (hog) or `llma-evaluation-run` against one generation (llm_judge; skip the
+spot-run for a judge with no usable key, per 2.3).
 Both tools currently use generation samples; for a trace target they can check shared source or prompt behavior,
 but they do not reproduce the complete settled trace. Review the first live trace results before increasing rollout.
 
@@ -354,8 +360,9 @@ creating so the user can review and toggle it in the UI.
   criterion genuinely can't be coded.
 - **Always create disabled, verify scope, then enable.** An eval firing on the wrong events is worse than
   none — noise, and (for llm_judge) cost.
-- **Configure llm_judge credentials before running.** A judge needs a valid provider and model plus a usable
-  provider key. `provider_key_id` may be `null` only when the matching active team key can be used.
+- **A judge draft needs only a provider and model.** A usable provider key is needed to enable it, not to
+  save it, so no `ok` key means keep it disabled — not stop. `provider_key_id` may be `null` to run on the
+  team's active key.
 - **`bytecode` is server-written** for hog evals — never pass it; send only `evaluation_config.source`.
 - For cluster-scoped evals, identify the cluster with `exploring-llm-clusters`, then translate its event
   filter into `conditions`.
diff --git a/skills/creating-online-evaluations/references/evaluation-payload.md b/skills/creating-online-evaluations/references/evaluation-payload.md
index 1580785..1bee939 100644
--- a/skills/creating-online-evaluations/references/evaluation-payload.md
+++ b/skills/creating-online-evaluations/references/evaluation-payload.md
@@ -152,11 +152,12 @@ Empty object: `{}`.
 | ----------------- | -------- | ------------------------------------------------------------------------------ |
 | `provider`        | yes      | One of `openai`, `anthropic`, `gemini`, `openrouter`, `fireworks`, `azure_openai`, `together_ai`. |
 | `model`           | yes      | Model id, e.g. `gpt-5-mini`. Validate against `llma-evaluation-judge-models`.  |
-| `provider_key_id` | no       | UUID of an `ok`-state key for the same provider. `null` uses the matching active team key. |
+| `provider_key_id` | no       | UUID of an `ok`-state key for the same provider, or `null` to use the active team key. |
 
-`provider` and `model` are required. Pin `provider_key_id` to run on one specific key. Leave it `null` only
-when `llma-evaluation-config-get` shows an `ok`-state active key for the same provider. A disabled draft may
-be saved without a usable key, but it cannot be tested or enabled until a key can be resolved.
+`provider` and `model` are required. Pin `provider_key_id` to run on one specific key, or set it to `null`
+to run on the team's active key — both save a valid draft. To enable an unpinned eval, the active key must
+be `ok` and use the same provider (`llma-evaluation-config-get` shows it). A disabled draft may be saved
+without a usable key, but it cannot be tested or enabled until a key can be resolved.
 
 ## `conditions`
 
@@ -250,7 +251,7 @@ and `item.output` when exact structure matters.
   "evaluation_config": { "prompt": "Return true if the assistant's reply stays on the user's topic, false if it changes subject. Return N/A if the user did not ask a question." },
   "output_type": "boolean",
   "output_config": { "allows_na": true },
-  "model_configuration": { "provider": "openai", "model": "gpt-5-mini", "provider_key_id": "<ok-state key uuid from llma-provider-key-list>" },
+  "model_configuration": { "provider": "openai", "model": "gpt-5-mini", "provider_key_id": null },
   "target": "generation",
   "target_config": {},
   "conditions": [{ "id": "default", "rollout_percentage": 100, "properties": [] }],
@@ -258,5 +259,6 @@ and `item.output` when exact structure matters.
 }
 ```
 
-Set `provider_key_id` to `null` only when the team's active key is in the `ok` state and its provider is
-`openai`.
+`provider_key_id: null` runs on the team's active key and always saves a valid draft. Pin it to an
+`ok`-state key uuid from `llma-provider-key-list` to run on one specific key. To enable an unpinned eval,
+the team's active key must be `ok` and its provider `openai`.
diff --git a/skills/inbox-exploration/SKILL.md b/skills/inbox-exploration/SKILL.md
index 2fbdd04..f728594 100644
--- a/skills/inbox-exploration/SKILL.md
+++ b/skills/inbox-exploration/SKILL.md
@@ -60,6 +60,7 @@ _underlying detail_ — pair them when the user wants to dig in.
 | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
 | `inbox-reports-list`                  | Paginated list of reports with filters (status, search, etc.)                                                 |
 | `inbox-reports-retrieve`              | Full detail for a single report                                                                               |
+| `inbox-reports-claim`                 | Claim or release a report, and optionally attach its implementation PR                                        |
 | `inbox-report-artefacts-list`         | A report's full work log — `signal_finding` evidence, status judgments, commits, task runs, notes (read-only) |
 | `inbox-report-artefacts-retrieve`     | Full detail for a single artefact (read-only)                                                                 |
 | `inbox-reports-set-state`             | Resolve (`resolved`), dismiss (`suppressed`), or snooze (`potential`) a single report                         |
@@ -71,12 +72,12 @@ _underlying detail_ — pair them when the user wants to dig in.
 
 The `inbox-reports-*-list` / `-retrieve`, `inbox-report-artefacts-list` / `-retrieve`, and
 `inbox-source-configs-*-list` / `-retrieve` tools are read-only. The exposed writes are `inbox-reports-set-state` (resolve / dismiss / snooze a single report),
-`inbox-reports-bulk-set-state` (the same transition for 1–100 reports in one call) — see
+`inbox-reports-bulk-set-state` (the same transition for 1–100 reports in one call),
+`inbox-reports-claim` (claim / release / attach a PR), see
 _Workflow: resolve, dismiss, or snooze a report_ — and `inbox-source-configs-partial-update`, which flips a
 source's `enabled` flag on or off (e.g. `{enabled: false}` to stop a source feeding the inbox);
-`-create` / `-update` exist too for standing a source up or replacing it wholesale. Other writes
-(pause processing, set `implementation_pr_url`) are not exposed via MCP today — the PR link is
-populated on the product surface when a PR is opened against a report.
+`-create` / `-update` exist too for standing a source up or replacing it wholesale. Pausing
+processing is not exposed via MCP.
 
 ## Terminology
 
@@ -198,6 +199,10 @@ inbox-reports-list
 If `count: 0` comes back, jump to the empty/unconfigured workflow above before saying "your
 inbox is empty" — the right reply depends on whether sources are configured.
 
+A claimed report keeps its pipeline status, so this queue also returns work someone else already
+owns. Add `"unclaimed": true` when the user is asking what is free to pick up, and
+`"assignee": "me"` to list what the caller already owns and may want to resume.
+
 ### Step 2 — Summarize by source and actionability
 
 For each report, the response includes:
@@ -211,6 +216,10 @@ For each report, the response includes:
   report (see "What 'suggested reviewer' means" above — it's based on GitHub commit
   authorship of the relevant code, mapped to PostHog users via linked GitHub identity)
 - `implementation_pr_url` — if a PR has been opened against this report
+- `work_state` — `unclaimed`, `working`, `in_review`, or `done`
+- `assignee` — who claimed the report (a user, an internal task, or an external agent), or `null`
+  when nobody has. Say so when you list a report someone else owns, so it doesn't read as free
+  work
 - `_posthogUrl` — clickable deep-link to the report; **always include this in your response**
 
 Group the results so the user can scan quickly. **Lead with reports where
@@ -285,7 +294,7 @@ implement.** Reports from `signals_scout` (and any LLM-research source) are espe
 double-checking; their `summary` often reads as a confident root-cause with file and function
 names, but it can be stale or wrong.
 
-### Step 1 — Retrieve and check it isn't already handled
+### Step 1 — Retrieve, check existing work, and claim it
 
 ```json
 inbox-reports-retrieve
@@ -297,9 +306,23 @@ Before doing any work, look at:
 - `already_addressed` — if `true`, the fix may already be in flight or merged; confirm with the
   user before duplicating it.
 - `implementation_pr_url` — if a PR is already linked, surface it instead of opening a second one.
+- `work_state` and `assignee` — show whether someone else has already picked it up. A takeover is
+  allowed, but make it deliberate rather than overlooking active work.
 - `status` — only `ready` reports carry a finished judgment. A `candidate` / `pending_input`
   report hasn't been researched yet; don't implement off a half-formed summary.
 
+Before starting research or implementation, claim the report:
+
+```json
+posthog:inbox-reports-claim
+{ "report_id": "<report_uuid>" }
+```
+
+The claim is attributed to the current internal task or external MCP client. Claims do not expire, so
+release the report whenever you walk away without landing a fix — including when you dismiss it instead.
+Release clears ownership only; an attached pull request stays on the report, and release works from any
+status, so a dismissed report can be released too.
+
 ### Step 2 — Verify the diagnosis against the code (do not skip)
 
 Start by reading the report's work log — its evidence and the judgments behind it:
@@ -317,7 +340,13 @@ way the report describes, and actually produces the described failure. As a deep
 the raw underlying signals via the `signals` skill (`metadata.report_id`) if you need the signal
 text behind the curated findings. If the diagnosis doesn't hold up, say so and stop — a wrong
 report is itself a useful finding (and a candidate for _dismiss_ below), not a license to write a
-speculative fix.
+speculative fix. Release the claim you took in Step 1 before you stop, so the report returns to the
+unclaimed view instead of reading as active work nobody is doing:
+
+```json
+posthog:inbox-reports-claim
+{ "report_id": "<report_uuid>", "release": true }
+```
 
 ### Step 3 — Scope the fix to the right layer
 
@@ -329,15 +358,25 @@ speculative fix.
   area-specific skills), make the change minimal, and add a regression test that would have caught
   the reported failure.
 
-### Step 4 — Open the PR and link it back
+### Step 4 — Open the PR and attach it
+
+Open the PR following the repo's PR conventions, then attach it to the report:
+
+```json
+posthog:inbox-reports-claim
+{
+  "report_id": "<report_uuid>",
+  "pr_url": "https://github.com/example/repository/pull/123"
+}
+```
 
-Open the PR following the repo's PR conventions. There is no MCP tool to set
-`implementation_pr_url` — that link is populated on the product surface when a PR is opened
-against the report. So reference the report in the PR description (its `_posthogUrl`) and tell the
-user which report the PR addresses, so the loop is traceable.
+The same PR may be attached to multiple reports. Connected repositories receive immediate state
+validation and webhook updates. PRs from unconnected repositories are accepted with unknown state,
+so resolve those reports manually after the work lands. Also reference the report's `_posthogUrl`
+in the PR description so the loop is traceable from either side.
 
-**Don't resolve a report because you opened a PR.** When the fix ships as a PR, the merge is what
-resolves the report — the tasks GitHub webhook does it automatically. Resolving by hand at PR-open
+**Don't resolve a report because you opened a PR.** When the fix ships as a connected PR, the merge
+resolves the report automatically. Resolving by hand at PR-open
 time asserts work that hasn't landed, and a reviewer looking at the inbox can't tell the difference.
 Manual resolve is for fixes a PR merge will never cover — a skill-body change, a config change, a
 `NO_REPO` report — see the workflow below.
@@ -488,12 +527,12 @@ inbox-source-configs-partial-update
 - `suppressed` reports are excluded by default; pass `status: "suppressed"` explicitly if the
   user wants to see hidden items
 - The inbox writes exposed via MCP are `inbox-reports-set-state` (resolve / dismiss / snooze one
-  report), `inbox-reports-bulk-set-state` (the same for 1–100 reports), and
+  report), `inbox-reports-bulk-set-state` (the same for 1–100 reports), `inbox-reports-claim`
+  (claim / release / attach a PR), and
   `inbox-source-configs-partial-update` (toggle a source's `enabled` flag). To _act_ on a report
-  (implement a fix), verify the diagnosis against the code first, then open a PR — see
+  (implement a fix), claim it, verify the diagnosis against the code, then open and attach a PR — see
   _Workflow: act on an actionable report_. A PR-backed fix is resolved automatically when the PR
-  merges, so don't resolve it by hand at PR-open time; setting `implementation_pr_url` happens on
-  the product surface, not via MCP. Always also surface the `_posthogUrl` deep-link
+  merges, so don't resolve it by hand at PR-open time. Always also surface the `_posthogUrl` deep-link
 - **Never implement a report's fix straight from its `summary`.** Reports — especially
   `signals_scout` ones — are LLM diagnoses; confirm the cited files / functions / behavior in the
   actual code before writing a fix. A report that doesn't hold up is a dismissal candidate, not a
diff --git a/skills/instrument-error-tracking/references/flutter.md b/skills/instrument-error-tracking/references/flutter.md
index 388ea1c..28c550f 100644
--- a/skills/instrument-error-tracking/references/flutter.md
+++ b/skills/instrument-error-tracking/references/flutter.md
@@ -108,7 +108,7 @@ Copy page
       <head>
         ...
         <script>
-          !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group identify setPersonProperties setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags resetGroups onFeatureFlags addFeatureFlagsHandler onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+          !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="init capture register register_once register_for_session unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group identify setPersonProperties setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags resetGroups onFeatureFlags addFeatureFlagsHandler onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
           posthog.init('<ph_project_token>', {
               api_host: 'https://us.i.posthog.com',
               defaults: '2026-05-30',
diff --git a/skills/instrument-error-tracking/references/web.md b/skills/instrument-error-tracking/references/web.md
index 7493f78..ba607c6 100644
--- a/skills/instrument-error-tracking/references/web.md
+++ b/skills/instrument-error-tracking/references/web.md
@@ -24,7 +24,7 @@ Copy page
 
     ```html
     <script>
-        !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+        !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
         posthog.init('<ph_project_token>', {
             api_host: 'https://us.i.posthog.com',
             defaults: '2026-05-30',
diff --git a/skills/instrument-feature-flags/references/flutter.md b/skills/instrument-feature-flags/references/flutter.md
index e9db83b..db9e679 100644
--- a/skills/instrument-feature-flags/references/flutter.md
+++ b/skills/instrument-feature-flags/references/flutter.md
@@ -108,7 +108,7 @@ Copy page
       <head>
         ...
         <script>
-          !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group identify setPersonProperties setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags resetGroups onFeatureFlags addFeatureFlagsHandler onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+          !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="init capture register register_once register_for_session unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group identify setPersonProperties setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags resetGroups onFeatureFlags addFeatureFlagsHandler onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
           posthog.init('<ph_project_token>', {
               api_host: 'https://us.i.posthog.com',
               defaults: '2026-05-30',
diff --git a/skills/instrument-feature-flags/references/web.md b/skills/instrument-feature-flags/references/web.md
index c1eb3e9..f6452eb 100644
--- a/skills/instrument-feature-flags/references/web.md
+++ b/skills/instrument-feature-flags/references/web.md
@@ -24,7 +24,7 @@ Copy page
 
     ```html
     <script>
-        !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+        !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagResult isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
         posthog.init('<ph_project_token>', {
             api_host: 'https://us.i.posthog.com',
             defaults: '2026-05-30',
diff --git a/skills/instrument-integration/references/posthog-js.md b/skills/instrument-integration/references/posthog-js.md
index c6ac710..b827d51 100644
--- a/skills/instrument-integration/references/posthog-js.md
+++ b/skills/instrument-integration/references/posthog-js.md
@@ -171,7 +171,7 @@ Set HMAC-based identity verification.
 
 **Notes:**
 
-When set, products like conversations use server-verified identity (distinct_id + HMAC hash) instead of anonymous session identifiers. The hash should be computed server-side as HMAC-SHA256 of the distinct_id using the project's API secret.
+When set, products like conversations use server-verified identity (distinct_id + HMAC hash) instead of anonymous session identifiers. The hash should be computed server-side as HMAC-SHA256 of the distinct_id using the project's API secret. Any additional signed identity claims are cleared because they are bound to the previously configured distinct_id.
 
 ### Parameters
 
@@ -553,7 +553,7 @@ By default, PostHog assigns each user a randomly generated `distinct_id`. Use th
 
 ### Parameters
 
-- **`new_distinct_id?`** (`string`) - A string that uniquely identifies a user. If not provided, the distinct_id currently in the persistent store (cookie or localStorage) will be used.
+- **`new_distinct_id`** (`string`) - A non-empty string that uniquely identifies a user.
 - **`userPropertiesToSet?`** (`Properties`) - Optional: An associative array of properties to store about the user. Note: For feature flag evaluations, if the same key is present in the userPropertiesToSetOnce, it will be overwritten by the value in userPropertiesToSet.
 - **`userPropertiesToSetOnce?`** (`Properties`) - Optional: An associative array of properties to store about the user. If property is previously set, this does not override that value.
 
diff --git a/skills/instrument-llm-analytics/references/anthropic.md b/skills/instrument-llm-analytics/references/anthropic.md
index 03f3c85..32c6099 100644
--- a/skills/instrument-llm-analytics/references/anthropic.md
+++ b/skills/instrument-llm-analytics/references/anthropic.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node @anthropic-ai/sdk
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/azure-openai.md b/skills/instrument-llm-analytics/references/azure-openai.md
index 00a3d72..264dae5 100644
--- a/skills/instrument-llm-analytics/references/azure-openai.md
+++ b/skills/instrument-llm-analytics/references/azure-openai.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/cerebras.md b/skills/instrument-llm-analytics/references/cerebras.md
index c5b9574..349b628 100644
--- a/skills/instrument-llm-analytics/references/cerebras.md
+++ b/skills/instrument-llm-analytics/references/cerebras.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/cohere.md b/skills/instrument-llm-analytics/references/cohere.md
index 1afe2fb..f6dc9b6 100644
--- a/skills/instrument-llm-analytics/references/cohere.md
+++ b/skills/instrument-llm-analytics/references/cohere.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/deepseek.md b/skills/instrument-llm-analytics/references/deepseek.md
index f4c60a7..48ee129 100644
--- a/skills/instrument-llm-analytics/references/deepseek.md
+++ b/skills/instrument-llm-analytics/references/deepseek.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/fireworks-ai.md b/skills/instrument-llm-analytics/references/fireworks-ai.md
index 2750cbf..fe73558 100644
--- a/skills/instrument-llm-analytics/references/fireworks-ai.md
+++ b/skills/instrument-llm-analytics/references/fireworks-ai.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/google.md b/skills/instrument-llm-analytics/references/google.md
index 1a50338..5682f60 100644
--- a/skills/instrument-llm-analytics/references/google.md
+++ b/skills/instrument-llm-analytics/references/google.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node @google/genai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/groq.md b/skills/instrument-llm-analytics/references/groq.md
index 183b566..6166ad5 100644
--- a/skills/instrument-llm-analytics/references/groq.md
+++ b/skills/instrument-llm-analytics/references/groq.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/helicone.md b/skills/instrument-llm-analytics/references/helicone.md
index f9eac9e..fd4a48d 100644
--- a/skills/instrument-llm-analytics/references/helicone.md
+++ b/skills/instrument-llm-analytics/references/helicone.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/hugging-face.md b/skills/instrument-llm-analytics/references/hugging-face.md
index b4bb818..049d521 100644
--- a/skills/instrument-llm-analytics/references/hugging-face.md
+++ b/skills/instrument-llm-analytics/references/hugging-face.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/mistral.md b/skills/instrument-llm-analytics/references/mistral.md
index 3e83a27..66b8bfd 100644
--- a/skills/instrument-llm-analytics/references/mistral.md
+++ b/skills/instrument-llm-analytics/references/mistral.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/ollama.md b/skills/instrument-llm-analytics/references/ollama.md
index 2c5cb28..d57d7df 100644
--- a/skills/instrument-llm-analytics/references/ollama.md
+++ b/skills/instrument-llm-analytics/references/ollama.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/openai.md b/skills/instrument-llm-analytics/references/openai.md
index 20d8255..43ab433 100644
--- a/skills/instrument-llm-analytics/references/openai.md
+++ b/skills/instrument-llm-analytics/references/openai.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/openrouter.md b/skills/instrument-llm-analytics/references/openrouter.md
index a585e11..88dc3d6 100644
--- a/skills/instrument-llm-analytics/references/openrouter.md
+++ b/skills/instrument-llm-analytics/references/openrouter.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/perplexity.md b/skills/instrument-llm-analytics/references/perplexity.md
index 3bdd086..7e6bd00 100644
--- a/skills/instrument-llm-analytics/references/perplexity.md
+++ b/skills/instrument-llm-analytics/references/perplexity.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/together-ai.md b/skills/instrument-llm-analytics/references/together-ai.md
index 50d7e43..2a5da29 100644
--- a/skills/instrument-llm-analytics/references/together-ai.md
+++ b/skills/instrument-llm-analytics/references/together-ai.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-llm-analytics/references/xai.md b/skills/instrument-llm-analytics/references/xai.md
index f2ec01d..f52b4f0 100644
--- a/skills/instrument-llm-analytics/references/xai.md
+++ b/skills/instrument-llm-analytics/references/xai.md
@@ -48,6 +48,12 @@ Skip the manual setup — run this in your project and the wizard installs the S
     npm install @posthog/ai posthog-node openai
     ```
 
+    ### Go
+
+    ```prose
+    PostHog doesn't have a Go wrapper for this SDK yet. Use the [OpenTelemetry integration](https://posthog.com/docs/ai-observability/installation/opentelemetry) instead.
+    ```
+
 2.  2
 
     ## Configure PostHog
diff --git a/skills/instrument-logs/references/best-practices.md b/skills/instrument-logs/references/best-practices.md
index d34c167..e3d6242 100644
--- a/skills/instrument-logs/references/best-practices.md
+++ b/skills/instrument-logs/references/best-practices.md
@@ -334,6 +334,8 @@ Match rules by service name, severity, or any log attribute. Rules run top to bo
 
 Because drop rules apply before storage, they're the fastest way to cut volume without shipping a code change. Pair them with the client-side practices above: sample at the source where you can, and use drop rules to catch the noise you can't.
 
+If you still want the trend from the lines you drop, add a [log-based metric](/docs/logs/metrics.md) first. Metric rules are evaluated before drop rules, so the count survives even though the logs don't.
+
 ## Add trace and session context
 
 Isolated logs are hard to correlate. Adding trace IDs and session IDs connects individual log events to the broader request journey.
diff --git a/skills/instrument-metrics/references/architecture.md b/skills/instrument-metrics/references/architecture.md
index 11244ee..67c0812 100644
--- a/skills/instrument-metrics/references/architecture.md
+++ b/skills/instrument-metrics/references/architecture.md
@@ -16,6 +16,8 @@ Metrics arrive over the OpenTelemetry Protocol (OTLP) via HTTP at `/i/v1/metrics
 
 Each incoming data point carries a metric name, a metric type, a value (or histogram buckets), a timestamp, resource attributes describing the sender (service name, host), and data point attributes describing the measurement (route, status). Ingestion validates the payload, applies your project's quota, and writes data points to a columnar time series store.
 
+Not every metric arrives over OTLP. A [log-based metric](/docs/logs/metrics.md) is generated at ingestion from your logs: log lines matching a rule are tallied as they arrive and emitted as a metric into the same store, so it shows up in the metrics viewer like any instrumented metric.
+
 ## The series model
 
 A **series** is one stream of values identified by the combination of:
@@ -49,6 +51,13 @@ Filters match attribute values with equality, negation, or regular expressions,
 
 Through the query API you can also combine multiple metrics with a formula, for example an error ratio computed as `errors / requests`, evaluated server side on the shared grid.
 
+## Anomaly detection and samples
+
+Two more things sit between storage and the chart:
+
+-   **Anomaly detection.** When you chart a metric, PostHog compares the most recent slice of the window against a baseline and, if they differ statistically, finds the onset and ranks which label values drove the move. That powers the anomaly badge and biggest-movers panel in the [viewer](/docs/metrics/explore.md).
+-   **Raw samples.** Alongside the aggregated series, PostHog keeps the individual emissions. The Samples view in the viewer reads these to show the exact data points behind a chart, and to link each one to the trace it was recorded in when trace context is present.
+
 ## Storage and SQL access
 
 Metrics are stored in a columnar time series table and exposed to SQL as `posthog.metrics`, scoped to your project like every other PostHog table. The SQL tab in the metrics viewer is a full escape hatch: anything the chart controls can't express, you can write directly, and join against the rest of your PostHog data.
diff --git a/skills/instrument-metrics/references/basics.md b/skills/instrument-metrics/references/basics.md
index f637b7c..5bdff04 100644
--- a/skills/instrument-metrics/references/basics.md
+++ b/skills/instrument-metrics/references/basics.md
@@ -46,7 +46,7 @@ The same goes for error budgets and latency. A `rate` on an error counter divide
 
 Most teams keep metrics in a separate system from everything else, so answering "did that latency spike affect signups?" means tab switching and timestamp matching. In PostHog, metrics live alongside your [logs](/docs/logs.md), [traces](/docs/distributed-tracing.md), product analytics, and session replays, in the same project with the same query language.
 
-Everything is queryable as SQL through the `posthog.metrics` table, and the [PostHog MCP server](/docs/model-context-protocol.md) exposes metrics to AI agents, so your tools can chart, compare, and investigate metrics for you.
+Everything is queryable as SQL through the `posthog.metrics` table, and the [PostHog MCP server](/docs/model-context-protocol.md) exposes metrics to AI agents, so your tools can chart, compare, and investigate metrics for you. When you chart a metric that has moved against its baseline, an anomaly badge surfaces the change and the label values behind it, and the raw samples stay linked to the logs and traces that explain them.
 
 ## Next steps
 
diff --git a/skills/instrument-metrics/references/start-here.md b/skills/instrument-metrics/references/start-here.md
index 8056ac6..15f1162 100644
--- a/skills/instrument-metrics/references/start-here.md
+++ b/skills/instrument-metrics/references/start-here.md
@@ -71,7 +71,7 @@ If you need to know what happened for one specific user or request, that's a job
 
 ## Verify metrics are arriving
 
-Open **Metrics** in the PostHog sidebar. Pick your metric from the name picker and you should see data points within a minute of sending. The viewer recommends an aggregation based on the metric's type, so a counter defaults to `increase` and a gauge to `avg`.
+Open **Metrics** in the PostHog sidebar. The **Overview** tab shows your services, metric names, and active series over the last day, so you can confirm data is landing. In the **Viewer** tab, pick your metric from the name picker and you should see data points within a minute of sending. The viewer recommends an aggregation based on the metric's type, so a counter defaults to `increase` and a gauge to `avg`.
 
 If nothing shows up, check that the endpoint ends in `/i/v1/metrics`, that the token starts with `phc_`, and see the [troubleshooting section](/docs/metrics.md#troubleshooting).
 
@@ -81,15 +81,19 @@ Once data flows, build the views you'll actually watch:
 
 -   **Group by** an attribute to get one line per value, for example request rate per route or queue depth per worker.
 -   **Filter** with `key=value` chips to focus on one service, environment, or status.
--   Switch to **stat mode** for a single headline number with an automatic comparison against the baseline.
--   Turn on **live** to refresh the chart every few seconds while you watch a deploy or an incident.
+-   Watch for the **anomaly badge** — when the metric moves against its baseline, it shows the change and the label values that drove it.
+-   Turn on **auto-refresh** to update the chart every few seconds while you watch a deploy or an incident.
+
+When a chart is worth keeping, **save it as an insight** or add it to a dashboard — or use **New service dashboard** to build one insight per metric in a single step.
 
 ## Query with SQL or ask AI
 
-Every metric lands in the `posthog.metrics` table, so the SQL tab in the metrics viewer gives you full query access for anything the chart controls don't cover.
+Every metric lands in the `posthog.metrics` table, so the **SQL** tab in the metrics viewer gives you full query access for anything the chart controls don't cover.
 
 If you use the [PostHog MCP server](/docs/model-context-protocol.md), your AI tools can query metrics directly: ask your agent to chart a metric, compare error rates between services, or characterize an anomaly, all without leaving your editor.
 
+For the full tour of the viewer — anomaly detection, pivoting into logs and traces, and dashboards — see [Use your metrics](/docs/metrics/explore.md).
+
 1/6
 
 [**Send your first metrics** ***Required***](#quest-item-send-your-first-metrics)[**Pick the right metric type** ***Required***](#quest-item-pick-the-right-metric-type)[**Add attributes, carefully** ***Required***](#quest-item-add-attributes-carefully)[**Verify metrics are arriving** ***Required***](#quest-item-verify-metrics-are-arriving)[**Chart what matters** ***Recommended***](#quest-item-chart-what-matters)[**Query with SQL or ask AI** ***Optional***](#quest-item-query-with-sql-or-ask-ai)
diff --git a/skills/managing-experiment-lifecycle/SKILL.md b/skills/managing-experiment-lifecycle/SKILL.md
index 5b6dff5..d349e1d 100644
--- a/skills/managing-experiment-lifecycle/SKILL.md
+++ b/skills/managing-experiment-lifecycle/SKILL.md
@@ -142,6 +142,17 @@ Required: `variant_key` (e.g. "test"). Optional: `conclusion`, `conclusion_comme
 
 Returns 409 if an approval policy requires review before the flag change.
 
+### Flag cleanup PR (option on end and ship variant)
+
+Both `experiment-end` and `experiment-ship-variant` accept `open_cleanup_pr: true`.
+A background PostHog Code task then removes the experiment's feature flag code and opens a draft pull request in the team's connected GitHub repository.
+
+- Only set this when the user asks for it or confirms it.
+- The key must carry the `task:write` scope, or the whole request is rejected with a 403 and the experiment is not ended or shipped.
+- The cleanup runs only when the call actually ends the experiment and a `conclusion` is set — shipping an already-stopped experiment, or ending without a conclusion, skips it. It also requires the team to have the flag cleanup feature enabled; silently skipped when it isn't.
+- `repository` ("organization/repository") picks the target when several repositories are connected. Omit it to fall back to the experiment's saved repository, the team default, or the only connected repository. With several candidates and no default, the cleanup is skipped unless provided.
+- Track progress with `experiment-cleanup-task` — the PR URL appears there once opened; a cleanup typically takes several minutes.
+
 ### Archive (`experiment-archive`)
 
 Hides a stopped experiment from the default list view.
diff --git a/skills/querying-posthog-data/SKILL.md b/skills/querying-posthog-data/SKILL.md
index bba5253..146fa4a 100644
--- a/skills/querying-posthog-data/SKILL.md
+++ b/skills/querying-posthog-data/SKILL.md
@@ -43,7 +43,7 @@ When the user asks for a governed business or telemetry measure (MRR, activation
    Create it only after the user says yes, with `posthog:data-catalog-metric-create`; when the definition came from a saved insight, pass that insight's `source_insight_short_id` instead of copying its query.
    Never offer for a one-off exploration or debugging aggregate, and never after an unknown-table error: a project with no data catalog has no `posthog:data-catalog-metric-create` either.
 
-Curating the catalog — creating or approving metrics, certifying sources, reviewing the proposal queue — is a separate job covered by the `setting-up-data-catalog` skill. If you notice a clearly load-bearing or stale table while deriving, that skill covers proposing a trust mark on it. Everything an agent proposes lands unapproved for a human to promote, so never present a proposal as canonical.
+Curating the catalog — creating, approving, or retiring metrics, certifying sources, reviewing the proposal queue — is a separate job covered by the `setting-up-data-catalog` skill. If you notice a clearly load-bearing or stale table while deriving, that skill covers proposing a trust mark on it. Everything an agent proposes lands unapproved for a human to promote, so never present a proposal as canonical.
 
 ## Data Schema
 
diff --git a/skills/querying-posthog-data/references/example-error-tracking.md b/skills/querying-posthog-data/references/example-error-tracking.md
index 1d79a2b..cc41b16 100644
--- a/skills/querying-posthog-data/references/example-error-tracking.md
+++ b/skills/querying-posthog-data/references/example-error-tracking.md
@@ -25,14 +25,14 @@ FROM
         argMaxState(properties.$exception_functions.-1, timestamp) AS function_state,
         argMaxState(properties.$exception_sources.-1, timestamp) AS source_state,
         argMaxState(properties.$lib, timestamp) AS library_state,
-        least(19, intDiv(dateDiff('seconds', toDateTime(toDateTime('2026-09-02 11:00:00.000000')), timestamp), greatest(1, intDiv(dateDiff('seconds', toDateTime(toDateTime('2026-09-02 11:00:00.000000')), toDateTime(toDateTime('2026-09-03 11:46:01.108567'))), 20)))) AS bin_idx,
+        least(19, intDiv(dateDiff('seconds', toDateTime(toDateTime('2026-09-03 11:00:00.000000')), timestamp), greatest(1, intDiv(dateDiff('seconds', toDateTime(toDateTime('2026-09-03 11:00:00.000000')), toDateTime(toDateTime('2026-09-04 11:32:54.561578'))), 20)))) AS bin_idx,
         count() AS occ,
         uniqState(nullIf(e.$session_id, '')) AS sessions_state,
         uniqState(coalesce(nullIf(toString(e.event_person_id), '00000000-0000-0000-0000-000000000000'), e.distinct_id)) AS users_state
     FROM
         events AS e
     WHERE
-        and(equals(e.event, '$exception'), isNotNull(e.properties.$exception_fingerprint), true, greaterOrEquals(e.timestamp, toDateTime(toDateTime('2026-09-02 11:00:00.000000'))), lessOrEquals(e.timestamp, toDateTime(toDateTime('2026-09-03 11:46:01.108567'))), or(greater(position(lower(e.properties.$exception_types), lower('constant')), 0), greater(position(lower(e.properties.$exception_values), lower('constant')), 0), greater(position(lower(e.properties.$exception_sources), lower('constant')), 0), greater(position(lower(e.properties.$exception_functions), lower('constant')), 0), greater(position(lower(e.properties.email), lower('constant')), 0), greater(position(lower(e.person.properties.email), lower('constant')), 0)), equals(properties.tag, 'max_ai'))
+        and(equals(e.event, '$exception'), isNotNull(e.properties.$exception_fingerprint), true, greaterOrEquals(e.timestamp, toDateTime(toDateTime('2026-09-03 11:00:00.000000'))), lessOrEquals(e.timestamp, toDateTime(toDateTime('2026-09-04 11:32:54.561578'))), or(greater(position(lower(e.properties.$exception_types), lower('constant')), 0), greater(position(lower(e.properties.$exception_values), lower('constant')), 0), greater(position(lower(e.properties.$exception_sources), lower('constant')), 0), greater(position(lower(e.properties.$exception_functions), lower('constant')), 0), greater(position(lower(e.properties.email), lower('constant')), 0), greater(position(lower(e.person.properties.email), lower('constant')), 0)), equals(properties.tag, 'max_ai'))
     GROUP BY
         fp_hash,
         bin_idx) AS ev
diff --git a/skills/querying-posthog-data/references/example-logs.md b/skills/querying-posthog-data/references/example-logs.md
index bd0e57c..6f22448 100644
--- a/skills/querying-posthog-data/references/example-logs.md
+++ b/skills/querying-posthog-data/references/example-logs.md
@@ -31,7 +31,7 @@ SELECT
 FROM
     logs
 WHERE
-    and(and(greaterOrEquals(toStartOfDay(time_bucket), toStartOfDay(assumeNotNull(toDateTime('2025-12-09 00:00:00')))), lessOrEquals(toStartOfDay(time_bucket), toStartOfDay(assumeNotNull(toDateTime('2025-12-10 00:00:00'))))), 1, greaterOrEquals(timestamp, toDateTime('2026-09-02 11:46:01.788447')), indexHint(like(lower(body), '%timeout%')), ilike(toString(body), '%timeout%'), in(severity_text, tuple('warn', 'error', 'fatal')))
+    and(and(greaterOrEquals(toStartOfDay(time_bucket), toStartOfDay(assumeNotNull(toDateTime('2025-12-09 00:00:00')))), lessOrEquals(toStartOfDay(time_bucket), toStartOfDay(assumeNotNull(toDateTime('2025-12-10 00:00:00'))))), 1, greaterOrEquals(timestamp, toDateTime('2026-09-03 11:32:55.485349')), indexHint(like(lower(body), '%timeout%')), ilike(toString(body), '%timeout%'), in(severity_text, tuple('warn', 'error', 'fatal')))
 ORDER BY
     timestamp DESC,
     uuid DESC
diff --git a/skills/querying-posthog-data/references/example-session-replay.md b/skills/querying-posthog-data/references/example-session-replay.md
index 0e79ed4..8ac4fd6 100644
--- a/skills/querying-posthog-data/references/example-session-replay.md
+++ b/skills/querying-posthog-data/references/example-session-replay.md
@@ -19,18 +19,18 @@ SELECT
     sum(s.console_error_count) AS console_error_count,
     max(s.retention_period_days) AS retention_period_days,
     plus(dateTrunc('DAY', start_time), toIntervalDay(coalesce(retention_period_days, 30))) AS expiry_time,
-    date_diff('DAY', toDateTime('2026-09-03 11:46:01.975713'), expiry_time) AS recording_ttl,
-    greaterOrEquals(max(s._timestamp), toDateTime('2026-09-03 11:41:01.975313')) AS ongoing,
+    date_diff('DAY', toDateTime('2026-09-04 11:32:55.808943'), expiry_time) AS recording_ttl,
+    greaterOrEquals(max(s._timestamp), toDateTime('2026-09-04 11:27:55.808448')) AS ongoing,
     round(least(greatest(multiply(divide(plus(plus(plus(divide(sum(s.active_milliseconds), 1000), sum(s.click_count)), sum(s.keypress_count)), sum(s.console_error_count)), plus(plus(plus(plus(sum(s.mouse_activity_count), dateDiff('SECOND', start_time, end_time)), sum(s.console_error_count)), sum(s.console_log_count)), sum(s.console_warn_count))), 100), 0), 100), 2) AS activity_score,
     coalesce(max(s.surfacing_score), 0.36) AS surfacing_score
 FROM
     raw_session_replay_events AS s
 WHERE
-    and(greaterOrEquals(s.min_first_timestamp, toDateTime('2026-08-31 00:00:00.000000')), lessOrEquals(s.min_first_timestamp, toDateTime('2026-09-03 11:46:01.975461')))
+    and(greaterOrEquals(s.min_first_timestamp, toDateTime('2026-09-01 00:00:00.000000')), lessOrEquals(s.min_first_timestamp, toDateTime('2026-09-04 11:32:55.808631')))
 GROUP BY
     session_id
 HAVING
-    and(greaterOrEquals(expiry_time, toDateTime('2026-09-03 11:46:01.975601')), equals(max(s.is_deleted), 0), greater(active_seconds, 5.0))
+    and(greaterOrEquals(expiry_time, toDateTime('2026-09-04 11:32:55.808831')), equals(max(s.is_deleted), 0), greater(active_seconds, 5.0))
 ORDER BY
     start_time DESC,
     session_id DESC
diff --git a/skills/querying-posthog-data/references/example-sessions.md b/skills/querying-posthog-data/references/example-sessions.md
index 5a1f700..2d0f1f9 100644
--- a/skills/querying-posthog-data/references/example-sessions.md
+++ b/skills/querying-posthog-data/references/example-sessions.md
@@ -13,7 +13,7 @@ SELECT
 FROM
     sessions
 WHERE
-    and(less($start_timestamp, toDateTime('2026-09-03 11:46:07.477242')), greater($start_timestamp, toDateTime('2026-09-02 11:46:02.477503')))
+    and(less($start_timestamp, toDateTime('2026-09-04 11:33:01.692858')), greater($start_timestamp, toDateTime('2026-09-03 11:32:56.693203')))
 ORDER BY
     $start_timestamp DESC
 LIMIT 50000
diff --git a/skills/resolving-ingestion-warnings/SKILL.md b/skills/resolving-ingestion-warnings/SKILL.md
index 32152cc..7f6f3c0 100644
--- a/skills/resolving-ingestion-warnings/SKILL.md
+++ b/skills/resolving-ingestion-warnings/SKILL.md
@@ -48,11 +48,13 @@ Those decisions come only from this skill's guidance and your own reasoning.
 
 ### Person merges (`merge`)
 
-| Type                                    | What happened                                                                                            | Fix                                                                                                                                                                                                                                         |
-| --------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cannot_merge_already_identified`       | Merge refused: both persons are already identified. The accounts silently stayed separate                | Read [references/fixing-cannot-merge-already-identified.md](references/fixing-cannot-merge-already-identified.md) — covers the identify/reset flow fixes; joining two identified users is a manual one-off decision, never application code |
-| `cannot_merge_with_illegal_distinct_id` | Merge refused: the distinct ID is a placeholder (`undefined`, `null`, `[object Object]`, `anonymous`, …) | Read [references/fixing-invalid-distinct-ids.md](references/fixing-invalid-distinct-ids.md) — a variable is unset at the identify/alias callsite                                                                                            |
-| `merge_race_condition`                  | Concurrent merges collided on the same persons; the operation was dropped                                | Read [references/fixing-merge-race-condition.md](references/fixing-merge-race-condition.md) — dedupe parallel identify calls, and check for a "mega person" merge magnet (thousands of distinct IDs on one person)                          |
+| Type                                    | What happened                                                                                               | Fix                                                                                                                                                                                                                                         |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cannot_merge_already_identified`       | Merge refused: both persons are already identified. The accounts silently stayed separate                   | Read [references/fixing-cannot-merge-already-identified.md](references/fixing-cannot-merge-already-identified.md) — covers the identify/reset flow fixes; joining two identified users is a manual one-off decision, never application code |
+| `cannot_merge_with_illegal_distinct_id` | Merge refused: the distinct ID is a placeholder (`undefined`, `null`, `[object Object]`, `anonymous`, …)    | Read [references/fixing-invalid-distinct-ids.md](references/fixing-invalid-distinct-ids.md) — a variable is unset at the identify/alias callsite                                                                                            |
+| `merge_race_condition`                  | Concurrent merges collided on the same persons; the operation was dropped                                   | Read [references/fixing-merge-race-condition.md](references/fixing-merge-race-condition.md) — dedupe parallel identify calls, and check for a "mega person" merge magnet (thousands of distinct IDs on one person)                          |
+| `merge_move_limit_exceeded`             | Merge dropped: the source person has more distinct IDs than one merge may move                              | A "mega person" merge magnet has accumulated thousands of distinct IDs. Same diagnosis as `merge_race_condition`: find the magnet and stop identifying against it                                                                           |
+| `merge_settled_failure`                 | The merge settled on a verdict that merged nothing, and the verdict is recorded so a retry cannot change it | Rare and not caller-fixable. Check whether the identity service is healthy; the accounts stay separate and a later identify under a fresh event uuid can still merge them                                                                   |
 
 ### Event validation (`event`)
 
diff --git a/skills/setting-up-data-catalog/SKILL.md b/skills/setting-up-data-catalog/SKILL.md
index df53975..eab9741 100644
--- a/skills/setting-up-data-catalog/SKILL.md
+++ b/skills/setting-up-data-catalog/SKILL.md
@@ -85,12 +85,18 @@ Work top-down, stopping at `proposed` for everything (a human promotes later):
 2. **Summarize each proposal with its evidence** (match rates, sample values, drift state) so a human
    can decide quickly.
 
-3. **On the human's instruction**, promote with the confirmed-action tools:
-   `posthog:data-catalog-metric-approve`, `posthog:data-catalog-certification-certify` / `-deprecate`,
-   `posthog:data-catalog-relationship-accept` / `-reject` (pass the `id` from the queue). A row proposed
-   with `proposed_status: 'deprecated'` is settled with `-deprecate`; the approver can reject that intent
-   by certifying instead, since `-deprecate` / `-certify` act on any non-deprecated row regardless of the
-   proposal's intent. A rejected relationship is suppressed forever, so only reject when the human is sure.
+3. **On the human's instruction**, promote with the confirmed-action tools. Each promotion is a two-step
+   tool: call the `-prepare` variant, surface the confirmation message it returns, wait for the user to
+   type the literal `confirm`, then call the matching `-execute` variant with the returned hash. The pairs
+   are `posthog:data-catalog-metric-approve-prepare` / `-execute`,
+   `posthog:data-catalog-certification-certify-prepare` / `-execute`,
+   `posthog:data-catalog-certification-deprecate-prepare` / `-execute`,
+   `posthog:data-catalog-relationship-accept-prepare` / `-execute`, and
+   `posthog:data-catalog-relationship-reject-prepare` / `-execute` (pass the `id` from the queue). A row
+   proposed with `proposed_status: 'deprecated'` is settled with the deprecate pair; the approver can
+   reject that intent by certifying instead, since deprecate and certify act on any non-deprecated row
+   regardless of the proposal's intent. A rejected relationship is suppressed forever, so only reject when
+   the human is sure.
 
 4. **Handle drift.** A metric with `is_drifted = true` has diverged from its source insight (or the
    insight is gone). It cannot be approved until the drift is cleared. Surface it for the human rather
@@ -102,6 +108,15 @@ Work top-down, stopping at `proposed` for everything (a human promotes later):
    The `refresh` parameter on `posthog:data-catalog-metric-run` is a query-cache mode, not a drift fix —
    it does not re-snapshot the linked insight.
 
+5. **Retire a metric that should not exist.** Delete with the signed confirmation flow:
+   `posthog:data-catalog-metric-delete-prepare`, then `posthog:data-catalog-metric-delete-execute`. Use it when the
+   metric duplicates another one, has been superseded, or measures something the team never wanted — not when it is
+   merely stale, wrongly defined, or badly named. For those, `posthog:data-catalog-metric-update` keeps the metric's
+   history and its `id`; `new_name` renames it in place. Surface the prepared message, wait for the human to reply with
+   the literal word `confirm`, then call execute with only the signed confirmation fields. Say what the delete costs:
+   an approved metric loses its human vouching, saved SQL and run URLs that name it stop resolving, and the freed name
+   may later be claimed by an unrelated metric, so a stored name is not a stable reference across a delete.
+
 ## Related
 
 Certifying a source says a human vouches for it. Proving it is _still_ correct is a separate job —
diff --git a/skills/understanding-billing-usage/references/usage-type-routing.md b/skills/understanding-billing-usage/references/usage-type-routing.md
index 2399cf6..c30b0d3 100644
--- a/skills/understanding-billing-usage/references/usage-type-routing.md
+++ b/skills/understanding-billing-usage/references/usage-type-routing.md
@@ -28,31 +28,32 @@ Useful downstream skills for usage investigations include:
 - `posthog:exploring-replay-vision-observations` when Replay Vision credits point to scanner
   observations.
 
-| Usage type                                        | What Billing can show                                                | Customer-visible follow-up                                                                                                                                                                                                                                                                     |
-| ------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `event_count_in_period`                           | Events by day/project                                                | Use `posthog:investigate-metric` or Product Analytics SQL/insight tools on the affected project. Break down by event name and compare the alert/high-usage day to baseline days. If `$autocapture` dominates, continue with `posthog:exploring-autocapture-events`.                            |
-| `enhanced_persons_event_count_in_period`          | Identified events by day/project                                     | Start like Events, using `posthog:investigate-metric` when available, but avoid claiming the raw event-name breakdown exactly explains the identified/anonymous split unless that dimension is visible.                                                                                        |
-| `group_analytics`                                 | Group Analytics spend/usage attribution using identified-event usage | Treat as an alias-style product view. Use identified-event/Product Analytics drilldown, usually via `posthog:investigate-metric`, and explain that the Billing view is product-specific attribution, not a separate raw event stream.                                                          |
-| `recording_count_in_period`                       | Session recordings by day/project                                    | Use Session Replay tools or the Replay UI for recording volume, SDK/platform filters, and representative sessions. Use `posthog:investigating-replay` only after you have representative recording/session IDs.                                                                                |
-| `mobile_recording_count_in_period`                | Mobile recordings by day/project                                     | Use Session Replay/mobile replay surfaces. Look for mobile SDK/platform mix before suggesting product changes. Use `posthog:investigating-replay` only after you have representative mobile recording/session IDs.                                                                             |
-| `billable_feature_flag_requests_count_in_period`  | Feature flag requests by day/project                                 | Use feature flag tools, flag configuration, and activity history. The billable unit is flag evaluation/API request volume, not `$feature_flag_called` events. Do not use stale-flag cleanup workflows unless the user asks how to remove unused flags.                                         |
-| `exceptions_captured_in_period`                   | Exceptions by day/project                                            | Use Error Tracking issue tools and `$exception` aggregates in the affected project. If one issue dominates the movement, use `posthog:investigating-error-issue`. UI issue counts are grouped context, while Billing usage is captured exception volume.                                       |
-| `survey_responses_count_in_period`                | Survey responses by day/project                                      | Use survey tools and survey events such as `survey shown` and `survey sent` to distinguish reach from response-rate changes. Use `posthog:debugging-surveys` when the investigation turns into "why is this survey showing, not showing, or getting fewer/more responses than expected?"       |
-| `ai_event_count_in_period`                        | AI Observability events by day/project                               | Use AI Observability tools or SQL over `$ai_*` events in the affected project. Break down by provider/model/trace/user only when those properties are available. Use `posthog:exploring-llm-costs` for cost-shaped questions and `posthog:analyzing-expensive-users` for user-level drivers.   |
-| `ai_credits_used_in_period`                       | PostHog AI credits by day/project                                    | Use PostHog AI or AI Observability surfaces exposed to the user. Prefer `posthog:exploring-llm-costs` for credit/spend movement and `posthog:analyzing-expensive-users` for concentrated user drivers. Do not inspect internal PostHog-owned AI telemetry in a customer-facing investigation.  |
-| `signals_credits_used_in_period`                  | Inbox credits by day/project                                         | Use Signals/Inbox product tools when available. Start with `posthog:inbox-exploration` for report-level context; use `posthog:signals` only when raw signal search is needed. Billing shows chargeable credit movement; product tools should explain reports/PRs/refunds.                      |
-| `posthog_code_credits_used_in_period`             | PostHog Desktop credits by day/project                               | Use PostHog Desktop usage surfaces when available. Treat token credits and sandbox compute as possible sub-drivers if exposed.                                                                                                                                                                 |
-| `posthog_code_token_credits_used_in_period`       | PostHog Desktop token credits by day/project                         | Use PostHog Desktop/AI usage surfaces when available.                                                                                                                                                                                                                                          |
-| `sandbox_compute_credits_used_in_period`          | Sandbox compute credits by day/project                               | Use task/sandbox/PostHog Desktop surfaces when available.                                                                                                                                                                                                                                      |
-| `sandbox_compute_cpu_millicore_seconds_in_period` | Sandbox CPU usage by day/project                                     | Use task/sandbox surfaces when available. This is a raw usage diagnostic, not usually the headline spend type.                                                                                                                                                                                 |
-| `sandbox_compute_memory_mib_seconds_in_period`    | Sandbox memory usage by day/project                                  | Use task/sandbox surfaces when available. This is a raw usage diagnostic, not usually the headline spend type.                                                                                                                                                                                 |
-| `rows_synced_in_period`                           | Data Warehouse synced rows by day/project                            | Use Data Warehouse source/schema health and sync tools. Look for new sources, enabled schemas, failed/stale syncs, or expected backfills. Use `posthog:auditing-warehouse-source-health` for a project-wide scan and `posthog:diagnosing-failed-warehouse-syncs` for a specific source/schema. |
-| `free_historical_rows_synced_in_period`           | Historical synced rows by day/project                                | Use Data Warehouse source/schema tools. Explain it as historical sync activity, not ongoing incremental volume. Use `posthog:auditing-warehouse-source-health` or `posthog:diagnosing-failed-warehouse-syncs` if a source or schema needs investigation.                                       |
-| `rows_exported_in_period`                         | Batch export rows by day/project                                     | Use batch export/CDP export tools and export configuration. Check newly enabled exports or changed destinations.                                                                                                                                                                               |
-| `data_pipelines`                                  | Legacy Data Pipelines product attribution                            | Treat as a legacy/synthetic product view. Use the Product Analytics or CDP surface that actually produced the usage, depending on the user's context.                                                                                                                                          |
-| `cdp_billable_invocations_in_period`              | Realtime destination trigger events by day/project                   | Use CDP function tools: list functions, inspect enabled destinations, metrics, and logs for the affected window.                                                                                                                                                                               |
-| `workflow_emails_sent_in_period`                  | Workflow emails by day/project                                       | Use Workflows tools: workflow stats, invocation logs, enabled workflows, and recent changes.                                                                                                                                                                                                   |
-| `workflow_billable_invocations_in_period`         | Workflow destination dispatches by day/project                       | Use Workflows tools and destination/invocation logs. Keep it separate from email volume.                                                                                                                                                                                                       |
-| `logs_mb_in_period`                               | Logs ingested in MB by day/project                                   | Use `posthog:investigating-logs` with Logs tools: service overview, count ranges, facets, and pattern diffs. Prefer log-specific tools over raw SQL.                                                                                                                                           |
-| `logs_retention_30d_mb_in_period`                 | Logs ingested under 30-day retention by day/project                  | Use `posthog:investigating-logs` with Logs tools and retention/settings surfaces. Explain that this is retention-tier usage, not separate log content.                                                                                                                                         |
-| `replay_vision_credits_used_in_period`            | Replay Vision credits by day/project                                 | Use Replay Vision scanner/observation tools. Credits come from scanner observations, so inspect scanners and observation status/results. Use `posthog:exploring-replay-vision-observations` when scanner observations are the natural drilldown.                                               |
+| Usage type                                        | What Billing can show                                                                | Customer-visible follow-up                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `event_count_in_period`                           | Events by day/project                                                                | Use `posthog:investigate-metric` or Product Analytics SQL/insight tools on the affected project. Break down by event name and compare the alert/high-usage day to baseline days. If `$autocapture` dominates, continue with `posthog:exploring-autocapture-events`.                            |
+| `enhanced_persons_event_count_in_period`          | Identified events by day/project                                                     | Start like Events, using `posthog:investigate-metric` when available, but avoid claiming the raw event-name breakdown exactly explains the identified/anonymous split unless that dimension is visible.                                                                                        |
+| `group_analytics`                                 | Group Analytics spend/usage attribution using identified-event usage                 | Treat as an alias-style product view. Use identified-event/Product Analytics drilldown, usually via `posthog:investigate-metric`, and explain that the Billing view is product-specific attribution, not a separate raw event stream.                                                          |
+| `recording_count_in_period`                       | Session recordings by day/project                                                    | Use Session Replay tools or the Replay UI for recording volume, SDK/platform filters, and representative sessions. Use `posthog:investigating-replay` only after you have representative recording/session IDs.                                                                                |
+| `mobile_recording_count_in_period`                | Mobile recordings by day/project                                                     | Use Session Replay/mobile replay surfaces. Look for mobile SDK/platform mix before suggesting product changes. Use `posthog:investigating-replay` only after you have representative mobile recording/session IDs.                                                                             |
+| `billable_feature_flag_requests_count_in_period`  | Feature flag requests by day/project                                                 | Use feature flag tools, flag configuration, and activity history. The billable unit is flag evaluation/API request volume, not `$feature_flag_called` events. Do not use stale-flag cleanup workflows unless the user asks how to remove unused flags.                                         |
+| `exceptions_captured_in_period`                   | Exceptions by day/project                                                            | Use Error Tracking issue tools and `$exception` aggregates in the affected project. If one issue dominates the movement, use `posthog:investigating-error-issue`. UI issue counts are grouped context, while Billing usage is captured exception volume.                                       |
+| `survey_responses_count_in_period`                | Survey responses by day/project                                                      | Use survey tools and survey events such as `survey shown` and `survey sent` to distinguish reach from response-rate changes. Use `posthog:debugging-surveys` when the investigation turns into "why is this survey showing, not showing, or getting fewer/more responses than expected?"       |
+| `ai_event_count_in_period`                        | AI Observability events by day/project                                               | Use AI Observability tools or SQL over `$ai_*` events in the affected project. Break down by provider/model/trace/user only when those properties are available. Use `posthog:exploring-llm-costs` for cost-shaped questions and `posthog:analyzing-expensive-users` for user-level drivers.   |
+| `ai_credits_used_in_period`                       | PostHog AI credits by day/project                                                    | Use PostHog AI or AI Observability surfaces exposed to the user. Prefer `posthog:exploring-llm-costs` for credit/spend movement and `posthog:analyzing-expensive-users` for concentrated user drivers. Do not inspect internal PostHog-owned AI telemetry in a customer-facing investigation.  |
+| `signals_credits_used_in_period`                  | Inbox credits by day/project                                                         | Use Signals/Inbox product tools when available. Start with `posthog:inbox-exploration` for report-level context; use `posthog:signals` only when raw signal search is needed. Billing shows chargeable credit movement; product tools should explain reports/PRs/refunds.                      |
+| `posthog_code_credits_used_in_period`             | PostHog Desktop credits by day/project                                               | Use PostHog Desktop usage surfaces when available. Treat token credits and sandbox compute as possible sub-drivers if exposed.                                                                                                                                                                 |
+| `posthog_code_token_credits_used_in_period`       | PostHog Desktop token credits by day/project                                         | Use PostHog Desktop/AI usage surfaces when available.                                                                                                                                                                                                                                          |
+| `sandbox_compute_credits_used_in_period`          | Sandbox compute credits by day/project                                               | Use task/sandbox/PostHog Desktop surfaces when available.                                                                                                                                                                                                                                      |
+| `sandbox_compute_cpu_millicore_seconds_in_period` | Sandbox CPU usage by day/project                                                     | Use task/sandbox surfaces when available. This is a raw usage diagnostic, not usually the headline spend type.                                                                                                                                                                                 |
+| `sandbox_compute_memory_mib_seconds_in_period`    | Sandbox memory usage by day/project                                                  | Use task/sandbox surfaces when available. This is a raw usage diagnostic, not usually the headline spend type.                                                                                                                                                                                 |
+| `rows_synced_in_period`                           | Data Warehouse synced rows by day/project                                            | Use Data Warehouse source/schema health and sync tools. Look for new sources, enabled schemas, failed/stale syncs, or expected backfills. Use `posthog:auditing-warehouse-source-health` for a project-wide scan and `posthog:diagnosing-failed-warehouse-syncs` for a specific source/schema. |
+| `free_historical_rows_synced_in_period`           | Historical synced rows by day/project                                                | Use Data Warehouse source/schema tools. Explain it as historical sync activity, not ongoing incremental volume. Use `posthog:auditing-warehouse-source-health` or `posthog:diagnosing-failed-warehouse-syncs` if a source or schema needs investigation.                                       |
+| `rows_exported_in_period`                         | Batch export rows by day/project                                                     | Use batch export/CDP export tools and export configuration. Check newly enabled exports or changed destinations.                                                                                                                                                                               |
+| `data_pipelines`                                  | Legacy Data Pipelines product attribution                                            | Treat as a legacy/synthetic product view. Use the Product Analytics or CDP surface that actually produced the usage, depending on the user's context.                                                                                                                                          |
+| `cdp_billable_invocations_in_period`              | Realtime destination trigger events by day/project                                   | Use CDP function tools: list functions, inspect enabled destinations, metrics, and logs for the affected window.                                                                                                                                                                               |
+| `workflow_emails_sent_in_period`                  | Workflow emails by day/project                                                       | Use Workflows tools: workflow stats, invocation logs, enabled workflows, and recent changes.                                                                                                                                                                                                   |
+| `workflow_billable_invocations_in_period`         | Workflow destination dispatches by day/project                                       | Use Workflows tools and destination/invocation logs. Keep it separate from email volume.                                                                                                                                                                                                       |
+| `logs_mb_in_period`                               | Logs ingested in MB by day/project                                                   | Use `posthog:investigating-logs` with Logs tools: service overview, count ranges, facets, and pattern diffs. Prefer log-specific tools over raw SQL.                                                                                                                                           |
+| `logs_retention_30d_mb_in_period`                 | Logs ingested under 30-day retention by day/project                                  | Use `posthog:investigating-logs` with Logs tools and retention/settings surfaces. Explain that this is retention-tier usage, not separate log content.                                                                                                                                         |
+| `logs_retention_mb_days_in_period`                | Logs retention in MB-days (bytes ingested weighted by retention days) by day/project | Use `posthog:investigating-logs` with Logs tools and retention/settings surfaces. Explain that this is storage-duration usage (MB times days retained), not separate log content. Average retention days = this / `logs_mb_in_period`.                                                         |
+| `replay_vision_credits_used_in_period`            | Replay Vision credits by day/project                                                 | Use Replay Vision scanner/observation tools. Credits come from scanner observations, so inspect scanners and observation status/results. Use `posthog:exploring-replay-vision-observations` when scanner observations are the natural drilldown.                                               |