@uptimizr/agent-core 1.1.0 → 1.2.0

package/dist/writeTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeTools.js","sourceRoot":"","sources":["../src/writeTools.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -1,8 +1,9 @@
 # @uptimizr/agent-core
 
 > The framework-agnostic, browser-safe core for Uptimizr analytics agents: the single read-only
-> tool catalog over the collector query API, a headless LLM provider-adapter interface, and the
-> tool-calling loop. Defined once, consumed by MCP, the dashboard, and the demo (ADR 0050).
+> analytics tool catalog over the collector query API, the `annotate`-gated project-metadata tools,
+> a headless LLM provider-adapter interface, and the tool-calling loop. Defined once, consumed by
+> MCP, the dashboard, and the demo (ADR 0050). Events are read-only (ADR 0051 §9).
 
 ## Docs
 
@@ -11,7 +12,7 @@
 - [Integration & API reference](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md): the underlying query endpoints.
 - [Architecture Decision Records](https://github.com/RaananW/Uptimizr/tree/main/docs/adr): in-browser assistant (0050), privacy model (0003), thin backends (0005), consumer-facing agents (0017).
 
-## Tools (read-only)
+## Analytics tools (read-only)
 
 <!-- generated:registry-tool-names:start — generated by `pnpm gen:docs`; edit the metric registry, not this list -->
 
@@ -21,27 +22,175 @@
 `position_heatmap`, `session_trajectory`, `aggregate_paths`, `scene_coverage`, `camera_distance`,
 `click_rays`, `flow_links`, `top_meshes`, `mesh_sources`, `mesh_trend`, `mesh_dwell`,
 `mesh_blind_spots`, `mesh_interaction_kinds`, `mesh_reachability`, `dead_clicks`, `rage_clicks`,
-`hover_dwell`, `interaction_sources`, `top_input_actions`, `camera_gestures`, `navigation_stats`,
-`backtrack_ratio`, `perf_summary`, `render_scale_truth`, `perf_distribution`, `fps_histogram`,
-`frame_time_percentiles`, `jank_rate`, `perf_churn`, `perf_by_device`, `perf_by_scene`,
-`perf_heatmap`, `compile_stalls`, `resource_summary`, `resource_percentiles`, `stability_counts`,
-`graphics_diagnostics`, `error_heatmap`, `rendering_technology`, `capability_changes`,
-`xr_rotation`, `xr_sources`, `xr_abandonment`, `xr_locomotion`, `xr_tracking_quality`,
-`boundary_heatmap`, `boundary_heatmap_stats`, `xr_boundary_contacts`,
-`ar_placement_time_to_place`, `ar_placement_attempts`, `ar_placement_surfaces`, `funnel`,
-`scene_retention`, `load_bounce_funnel`, `variant_leaderboard`
+`hover_dwell`, `interaction_sources`, `top_input_actions`, `custom_event_vocabulary`,
+`camera_gestures`, `navigation_stats`, `backtrack_ratio`, `perf_summary`, `render_scale_truth`,
+`perf_distribution`, `fps_histogram`, `frame_time_percentiles`, `jank_rate`, `perf_churn`,
+`perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_summary`,
+`resource_percentiles`, `stability_counts`, `graphics_diagnostics`, `error_heatmap`,
+`rendering_technology`, `capability_changes`, `xr_rotation`, `xr_sources`, `xr_abandonment`,
+`xr_locomotion`, `xr_tracking_quality`, `boundary_heatmap`, `boundary_heatmap_stats`,
+`xr_boundary_contacts`, `ar_placement_time_to_place`, `ar_placement_attempts`,
+`ar_placement_surfaces`, `funnel`, `scene_retention`, `load_bounce_funnel`, `variant_leaderboard`,
+`insight_baseline`, `insight_movers`, `insight_anomalies`, `insight_significance`,
+`insight_scene_health`
+
+Only on a key holding `query:raw`, and only when the collector runs with
+`ENABLE_RAW_SESSION_RETENTION` (ADR 0003):
+
+`session_narrative`
 
 <!-- generated:registry-tool-names:end -->
 
+## Insight primitives (ADR 0051 §4)
+
+Five of the tools are readings *about* the other metrics, and they are the right first call on an
+open-ended question — "how are things?" does not mean "call thirty tools".
+
+- `insight_scene_health` — one 0-100 score per scene over six weighted factors (perf stability,
+  jank, errors, dead clicks, coverage, XR abandonment), least healthy first. The right *unscoped*
+  starting point: it answers which scene to open. Every factor carries the `metric` id behind it,
+  its `raw` value and the project `baseline` it was compared with, so the next call and the
+  sentence to write are both already in the row. **50 is the project norm, not a pass mark** — the
+  score compares a scene with the rest of the project's recent past — and a factor with
+  `score: null` was not counted (its `note` says why).
+- `insight_movers` — what changed against a reference window (the previous equal one by default),
+  for every comparable metric in scope, ranked by a robust z-score: the change divided by how much
+  that metric normally swings, so a noisy metric must move much further than a steady one to reach
+  the top. Bounded: at most 24 metrics are scanned per request.
+- `insight_baseline` — what is normal for one metric in one scene: `median` and `mad`, the
+  `p10`..`p90` band, and the drift `slope`. Call it on whatever moved, to say whether the new level
+  is actually outside normal rather than merely different.
+- `insight_anomalies` — *when* one metric went wrong. One row per bucket that does not belong in
+  the series: `kind: "spike" | "drop"` for a bucket more than `sensitivity` (default 3) standard
+  deviations from the trailing window, and `kind: "shift"` at the bucket where the level moved and
+  stayed moved. Where the metric declares a dimension it can be split by, `contributor` names the
+  mesh, source, input action, event type or scene holding the largest `share` of the excess.
+  Bounded: one scan for the series plus at most three attribution scans per request.
+- `insight_significance` — whether a difference between two windows could be chance: `effect`,
+  `ci95`, `p`, and the `test` that produced them (a two-proportion z with Wilson intervals for a
+  declared rate, Welch's t over the per-bucket values for a level, an exact Poisson rate test for a
+  bare count — picked from the measure, not from you). **Read `ci95` before `p`**: an interval that
+  straddles 0 means you cannot tell yet, and `powerNote` says what this much data could have
+  detected at all. Welch's `n` is the number of **buckets**, not events. It compares two *windows*,
+  not two segments: a variant-versus-variant question is a `400`, not a wrong answer.
+
+Read `insight_anomalies`' `z` as standard deviations and `insight_movers`' as the same ratio
+unscaled — they differ by a constant factor (1.4826) and must not be compared directly. A sustained
+level change is reported both as a `shift` and, for the days right after it, as `drop`/`spike`
+rows: two true statements about one event.
+
+Two fields decide whether a mover is worth reporting, and both are easy to misread:
+
+- `direction` is the registry's opinion of what a **rise** in that metric means — `up` (good),
+  `down` (bad) or `neutral`. It is *not* the direction of the move: read it with the sign of
+  `delta`, so a rise in a `down` metric (errors, dead clicks, jank) is a regression.
+- `aboveMinSample: false` means the delta is real arithmetic but the denominator is below the
+  metric's declared minimum. Such rows are returned rather than dropped — "we cannot tell" and
+  "nothing changed" are different answers — and must never be reported as findings.
+
+Statistics are computed in pure TypeScript over portable day/hour buckets, so the same data yields
+the same answer on every storage engine. Only `comparable` metrics with a faithful per-bucket form
+participate; asking for one that has none returns `400` naming every id that does.
+
+## Result formats (`format`)
+
+Every aggregate tool declares a `format` argument — the envelope its rows arrive in, not a filter
+(ADR 0051 §2). `buildRequest` applies `DEFAULT_TOOL_FORMAT` (`table`) when the caller names none
+and sends it explicitly, so the collector's own default stays `full`. A tool's output schema
+describes all three envelopes, so whichever one comes back validates.
+
+- `summary` — **prefer this whenever a model reads the result.** A bounded digest: `ranked` top
+  rows, a `series` trend, merged spatial `clusters`, or a single `record`, with shares, a sample
+  size, the metric's `caveats` and a templated `reading` sentence. Capped at the metric's
+  `limits.maxSummaryRows`, so a 500-bin heatmap costs the same as a 5-bin one — which is what keeps
+  one heatmap from filling a small local model's whole context.
+- `table` — **the tools' default.** `{ meta, rows }`: every row plus the metric, range, applied
+  filters, sample size, row count, a truncation flag and the registry limits. Self-describing but
+  not bounded — ask for `summary` when the result could be large.
+- `full` — the bare rows, with no envelope at all.
+
+`reading` and `caveats` are templated by pure code, never a model, so identical rows always produce
+identical words. Shares appear only where the measure can honestly be summed (an FPS or ratio metric
+reports `total: null` and no shares). Cluster coordinates are grid indices — multiply by the
+effective `cellSize` for world space. `session_meta` and `scene_representation` are stored records,
+not aggregations, and declare no `format`.
+
+## Packaged methodology skills (ADR 0051 §7)
+
+Shipped in this tarball as Agent Skills files under `skills/<name>/SKILL.md` — frontmatter (tools,
+capabilities, arguments) plus a numbered method. `AGENT_SKILLS` is those files compiled to data;
+`getAgentSkill(name)` resolves either spelling and `render(args)` substitutes the scene and range.
+The same files back `@uptimizr/mcp`'s prompt templates and `uptimizr agent report --skill`.
+
+<!-- generated:registry-skill-names:start — generated by `pnpm gen:docs`; edit the SKILL.md files, not this list -->
+
+- `attention_hotspots` (scene (required), range) — Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where to put a call to action, finding ignored or invisible content, explaining why an object gets no clicks, laying out a scene around what people actually look at.
+  Method: `skills/attention-hotspots/SKILL.md`. Tools: `camera_heatmap`, `flow_links`, `click_rays`, `top_meshes`, `mesh_dwell`, `mesh_blind_spots`, `query`.
+- `conversion_investigation` (scene, range) — Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the bounce that happens before the funnel even starts, scene-to-scene retention, variant performance, and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do people drop off", diagnosing a step nobody completes.
+  Method: `skills/conversion-investigation/SKILL.md`. Tools: `funnel`, `load_bounce_funnel`, `scene_retention`, `variant_leaderboard`, `dead_clicks`, `rage_clicks`, `mesh_reachability`, `flow_links`, `insight_significance`, `insight_movers`, `query`.
+- `performance_regression_triage` (scene, range) — Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene, device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower", a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.
+  Method: `skills/performance-regression-triage/SKILL.md`. Tools: `insight_movers`, `insight_anomalies`, `insight_significance`, `insight_baseline`, `perf_summary`, `perf_distribution`, `frame_time_percentiles`, `jank_rate`, `perf_by_device`, `perf_by_scene`, `perf_heatmap`, `compile_stalls`, `resource_percentiles`, `render_scale_truth`, `rendering_technology`, `query`.
+- `weekly_scene_health` (scene, range) — A weekly health check for a scene (or the whole project): a weighted health score with every factor traced back to the metric behind it, what changed against last week, traffic, event mix, performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?" review, a scheduled weekly or monthly report, a first look at a project you do not know yet, deciding which scene to investigate next.
+  Method: `skills/weekly-scene-health/SKILL.md`. Tools: `insight_scene_health`, `insight_movers`, `insight_baseline`, `insight_significance`, `insight_anomalies`, `event_counts`, `timeseries`, `perf_summary`, `top_meshes`, `list_sessions`, `query`.
+- `xr_comfort_audit` (scene, range) — Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style, tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end early, choosing a locomotion scheme, checking whether a play space is big enough.
+  Method: `skills/xr-comfort-audit/SKILL.md`. Tools: `xr_rotation`, `xr_locomotion`, `xr_abandonment`, `xr_sources`, `xr_tracking_quality`, `xr_boundary_contacts`, `boundary_heatmap_stats`, `insight_scene_health`, `insight_movers`, `query`.
+
+<!-- generated:registry-skill-names:end -->
+
 ## Key exports
 
 - `readTools` — the read-only tool catalog (one entry per query endpoint), generated from the
-  `@uptimizr/metrics` metric registry: 69 tools, each with an input schema, an output schema and the
-  metric's interpretation notes and caveats in its description (ADR 0051).
+  `@uptimizr/metrics` metric registry plus `query` and `list_subscriptions`: 77 tools, each with an
+  input schema, an output schema covering all three `format` envelopes, and the metric's
+  interpretation notes and caveats in its description (ADR 0051).
+- `writeTools` / `mutatingWriteTools` — the project-metadata tools `annotate`, `define_term`,
+  `save_analysis` (ADR 0051 §5), `pin_panel` and `unpin_panel` (ADR 0051 §7), plus the reads
+  `list_annotations`, `list_glossary`, `list_analyses`, `list_panels`. Exported individually too
+  (`annotateTool`, `defineTermTool`, `saveAnalysisTool`, `pinPanelTool`, `unpinPanelTool`,
+  `listAnnotationsTool`, `listGlossaryTool`, `listAnalysesTool`, `listPanelsTool`). A
+  separate export from `readTools` on purpose, so an integration's read-only stance stays
+  inspectable. They need an `annotate` key, write metadata only, and cannot touch an event.
+  `pin_panel` stores a panel **spec** — a metric id, a chart name, some column names — that the
+  dashboard renders with panels it already ships, so nothing is loaded and nothing is evaluated;
+  send the `query` document with `range: "inherit"` and a chart the metric's grain supports, or the
+  collector refuses it and names the charts that would have worked. `unpin_panel` removes a panel
+  for everyone on the project and is the one tool here that uses `CollectorClient.delete`.
 - `coreReadTools` / `selectReadTools(kind)` / `filterReadTools(names)` — narrowed views of the
   catalog for models that cannot carry every tool schema.
 - `registryToTools(metrics?)` — generate the catalog from metric-registry definitions.
-- `createCollectorClient(config)` — the thin GET-only collector client.
+- `createCollectorClient(config)` — the thin collector client: `get` for every analytics read, plus
+  `post`/`put`/`delete` used only by the metadata write tools.
 - `runAgent(options)` — the headless tool-calling loop (LLM ↔ tools ↔ collector).
 - `toToolSchemas(tools?)` — convert catalog tools to JSON-Schema tool descriptors for an LLM.
+- `renderContextForPrompt(context, nowMs?)` — render the collector's project context document
+  (`GET /api/v1/context`, ADR 0051 §5) as a compact system-prompt block: the project's real scene
+  ids, named region ids, custom-event names with their prop keys and coarse types, top meshes, input
+  actions, data freshness, retention flags and the metrics that are empty because their capture
+  channel is off. Pure, ~1.5 k characters at most, tolerant of a partial document, and `""` when
+  there is nothing to say — so an older collector degrades instead of failing. Read the context
+  first and inject this before the first question.
+- `AGENT_SKILLS` / `getAgentSkill(name)` / `renderAgentSkill(name, args)` — the curated
+  investigations packaged as `skills/<name>/SKILL.md` in this tarball (`attention_hotspots`,
+  `conversion_investigation`, `performance_regression_triage`, `weekly_scene_health`,
+  `xr_comfort_audit`): title, description, the registry tools each method relies on, its arguments,
+  and a pure `render(args)` producing the user turn. `@uptimizr/mcp` registers them as prompt
+  templates and `uptimizr agent report --skill` runs them headlessly, from this one definition.
+  `getAgentSkill` takes either spelling, and the pre-#316 name `xr_comfort_review` still resolves.
+- `ANALYTICS_AGENT_GUIDELINES` / `renderCurrentTimeLine(nowMs)` — the system-prompt fragments every
+  analytics agent shares (what it may claim about the data; the clock it resolves "this week"
+  against). Clients add only their own role sentence and output format.
 - `LlmProvider` — the pluggable, user-controlled LLM backend interface (no bundled model or key).
+- `ProviderResponse.usage` — optional `{ inputTokens?, outputTokens? }` per turn, populated by the
+  hosted adapters from Anthropic's `usage` and OpenAI's `prompt_tokens`/`completion_tokens`
+  (buffered and streamed). Absent means **not reported**, never zero.
+
+## Capability-gated tools (ADR 0051 §7)
+
+- `readTools` is the `query` surface; `rawTools` holds the tools whose registry endpoint declares `capability: "query:raw"` (today `session_narrative`, the compacted account of one session).
+- Keep them apart: the capability belongs to the key the agent was handed. Register `rawTools` only after `GET /api/v1/whoami` confirms `query:raw` — the collector also requires `ENABLE_RAW_SESSION_RETENTION`, so the capability is necessary but not sufficient (ADR 0003).
+
+## Non-metric reads
+
+- `list_subscriptions` — the project's conditional subscriptions (ADR 0051 §6). Not a registry
+  metric: configuration, not a measurement. No arguments, no time range. Creating/deleting one
+  needs `annotate` and is not a tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/agent-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Framework-agnostic, browser-safe core for Uptimizr analytics agents — the single read-only tool catalog over the collector query API, a headless LLM provider-adapter interface, and the tool-calling loop.",
   "keywords": [
     "uptimizr",
@@ -51,6 +51,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE",
     "AGENTS.md",
@@ -58,8 +59,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "zod": "^4.5.4",
-    "@uptimizr/metrics": "0.1.0"
+    "zod": "^4.6.5",
+    "@uptimizr/metrics": "0.2.0",
+    "@uptimizr/schema": "1.2.0"
   },
   "peerDependencies": {
     "@mlc-ai/web-llm": "^0.2.0"
@@ -70,9 +72,9 @@
     }
   },
   "devDependencies": {
-    "@mlc-ai/web-llm": "^0.2.84",
+    "@mlc-ai/web-llm": "^0.2.85",
     "esbuild": "^0.28.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=22"

package/skills/attention-hotspots/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: attention_hotspots
+title: Attention hot-spots for a scene
+description: >-
+  Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the
+  objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where
+  to put a call to action, finding ignored or invisible content, explaining why an object gets no
+  clicks, laying out a scene around what people actually look at. Trigger phrases: what do people
+  look at, attention hotspots, where do visitors click, which meshes get ignored, blind spots,
+  gaze heatmap, is anyone seeing this object.
+tools:
+  - camera_heatmap
+  - flow_links
+  - click_rays
+  - top_meshes
+  - mesh_dwell
+  - mesh_blind_spots
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: true
+    description: The scene id to analyse (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to analyse, in words — e.g. "the last 7 days", "since launch".
+---
+
+Where does attention concentrate in scene "{{scene}}" over {{range}}?
+
+Work through the method below with the read-only tools it names — all of them scoped with
+`scene="{{scene}}"` — and synthesise one answer.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first: it gives the
+   real scene ids, the scene's **named regions** and the custom-event names this project emits, and
+   it tells you which metrics are empty because their capture channel is off. Name regions the way
+   the project names them — "the checkout counter", not "the cluster at x≈3".
+
+2. **Where do they look?** `camera_heatmap` (`scene="{{scene}}"`) gives the view-direction
+   distribution — what people point the camera at, whether or not they ever click it. Ask for
+   `format: "summary"`: the digest merges neighbouring cells into a handful of clusters with a
+   share each and a plain-language `reading`, which is what you want here; the raw grid is
+   thousands of cells you cannot describe.
+
+3. **Does looking turn into touching?** `flow_links` (`scene="{{scene}}"`) links where the gaze was
+   to the mesh that was then clicked. A strong link is a working call to action; a heavy look with
+   no outgoing link is content that draws the eye and then disappoints.
+
+4. **Where do the clicks land?** `click_rays` (`scene="{{scene}}"`) gives view-gated clicks per
+   voxel and mesh — clicks attributed to what the visitor could actually see, not to whatever the
+   ray happened to pass through.
+
+5. **Rank the objects.** `top_meshes` (`scene="{{scene}}"`) for the most-interacted meshes, and
+   `mesh_dwell` (`scene="{{scene}}"`) for how long attention rests on each one. Dwell without
+   interaction is hesitation, and it usually means the object looks clickable and is not, or is
+   clickable and does not look it.
+
+6. **Name the cold half.** `mesh_blind_spots` (`scene="{{scene}}"`) lists the meshes that are
+   present and essentially never noticed. A hot-spot report that only names hot spots tells you
+   nothing about the content you paid to build.
+
+7. **Narrow it with the DSL.** For anything the canned tools do not expose, use the single `query`
+   tool: pick the `metric`, bound it with `range`, filter it, and set `format: "summary"` for a
+   bounded digest — each summary row carries a `drillQuery` you can send straight back instead of
+   rebuilding the filter. Set `compare: { range: <previous window> }` to see whether a hot spot is
+   new, and `explain: true` when a result looks wrong or empty: the plan names the capture channel,
+   the sample size and the row cap behind it.
+
+## What to report
+
+- The two or three real hot-spots, named with the project's own region and mesh names, each with
+  its share of attention.
+- The cold areas and the meshes nobody notices.
+- Where gaze fails to convert into interaction, and what that implies for layout and
+  call-to-action placement.
+
+Carry the caveats: heatmaps are gated on the view/pointer capture channels and are sampled
+(ADR 0012), so a share is a share _of the sampled events_; say so, and say when a result was
+truncated (`meta.truncated`) or sits below the metric's own minimum sample. Do not turn a voxel
+cluster into a claim about one object unless `click_rays` or `flow_links` attributes it to that
+mesh.
+
+End with 2–3 concrete layout or content recommendations. If an `annotate` tool is available, leave
+a note on the region you want revisited — a region-scoped annotation is what makes the next report
+open where this one ended. If a `pin_panel` tool is available, pin the heatmap panel you reasoned
+from.

package/skills/conversion-investigation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: conversion_investigation
+title: Conversion investigation
+description: >-
+  Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the
+  bounce that happens before the funnel even starts, scene-to-scene retention, variant performance,
+  and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled
+  step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do
+  people drop off", diagnosing a step nobody completes. Trigger phrases: conversion, funnel,
+  drop-off, why are people leaving, which variant wins, bounce rate, retention, people get stuck.
+tools:
+  - funnel
+  - load_bounce_funnel
+  - scene_retention
+  - variant_leaderboard
+  - dead_clicks
+  - rage_clicks
+  - mesh_reachability
+  - flow_links
+  - insight_significance
+  - insight_movers
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: false
+    description: Optional scene id to scope the investigation to (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to investigate, in words — e.g. "the last 7 days", "since the release".
+---
+
+Investigate conversion for {{scope}} over {{range}}: where do people drop off, and is the drop real?
+
+Work through the method below with the read-only tools it names, then answer.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first. A funnel is
+   built out of **this project's own event types and custom-event names** — invent one and every
+   step reads zero. The context document lists the vocabulary the application actually emits, the
+   real scene ids, and which metrics are empty because their capture channel is off.
+
+2. **Check the step before the first step.** `load_bounce_funnel`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   measures load → first interaction → stay. If people leave before the funnel starts, nothing
+   inside it will explain the number, and a "conversion problem" is really a load or a first-impression
+   problem.
+
+3. **Run the funnel itself.** `funnel`{{#scene}} (`scene="{{scene}}"`){{/scene}} with the `steps`
+   built from the context document's vocabulary. Read it as the _transition_ rates, not the totals:
+   the step with the worst step-to-step rate is the one to investigate, even when a later step has
+   fewer people in absolute terms.
+
+4. **Follow them out of the scene.** `scene_retention`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   shows where a visitor goes next. A step that "loses" people to the next scene is not a loss at
+   all; one that loses them to nothing is.
+
+5. **Explain the stalled step.** At the worst step, look for interaction failure rather than
+   intent: `dead_clicks` (clicks that hit nothing actionable), `rage_clicks` (repeated clicking in
+   one spot — frustration you can locate), `mesh_reachability` (the target is too far away or
+   behind something to be clicked at all) and `flow_links` (people look at the target and never
+   click it). One of these usually _is_ the drop-off.
+
+6. **Compare variants honestly.** `variant_leaderboard` ranks variants by conversion. A leaderboard
+   is not a verdict: check each variant's sample size before repeating its rate, and say plainly
+   when two variants are too close or too small to separate. `insight_significance` can test a
+   metric with a portable bucket series across two **windows**; it does not test one segment against
+   another, and if you ask it to it will say so — report that limitation rather than inventing a
+   p-value.
+
+7. **See whether this is new.** `insight_movers`{{#scene}} (`scene="{{scene}}"`){{/scene}} ranks
+   what changed against the previous equal window, so you can tell "this funnel has always been bad"
+   from "this funnel broke last Tuesday". Ignore any row with `aboveMinSample: false`.
+
+8. **Use the DSL for the cuts the canned tools do not expose.** The single `query` tool takes a
+   `metric`, a `range`, that metric's filters, and `compare: { range: <previous window> }` to return
+   `{ current, previous, delta, deltaPct }` already joined — do not subtract two runs by hand. Use
+   `dimensions` to regroup a portable count (by device class, source or scene) and
+   `format: "summary"` for a bounded digest with a `reading` and a `drillQuery` per row. When a step
+   reads zero, re-send it with `explain: true` before reporting it: the plan will tell you whether
+   the number is real or whether the channel behind it is switched off.
+
+## What to report
+
+- The step that actually loses people, with its entry and exit counts and its transition rate.
+- The mechanism, named: dead clicks on a specific mesh, an unreachable target, a bounce before the
+  first interaction, or a genuine loss of interest.
+- What each variant did, with sample sizes, and whether the difference can be told apart from noise.
+
+Carry the caveats into the text: funnel steps are only as good as the event vocabulary they were
+built from, a rate over a handful of sessions is not a rate, `meta.truncated` means you are looking
+at a cut-off list, and a disabled capture channel produces a zero that means "not measured".
+
+End with 2–3 concrete recommendations tied to the step and the mesh they apply to. If an `annotate`
+tool is available, leave a note on the failing step so the next investigation starts there, and use
+`save_analysis` to store the funnel definition you settled on — the next run should not have to
+guess the steps again. If a `pin_panel` tool is available, pin the funnel panel.

package/skills/performance-regression-triage/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: performance_regression_triage
+title: Performance regression triage
+description: >-
+  Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene,
+  device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory
+  pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower",
+  a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.
+  Trigger phrases: performance regression, FPS dropped, why is it slow, stutter, jank, frame drops,
+  did the last release slow things down, triage performance.
+tools:
+  - insight_movers
+  - insight_anomalies
+  - insight_significance
+  - insight_baseline
+  - perf_summary
+  - perf_distribution
+  - frame_time_percentiles
+  - jank_rate
+  - perf_by_device
+  - perf_by_scene
+  - perf_heatmap
+  - compile_stalls
+  - resource_percentiles
+  - render_scale_truth
+  - rendering_technology
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: false
+    description: Optional scene id to scope the triage to (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 14 days
+    description: The window to triage, in words — e.g. "the last 14 days", "since the release".
+---
+
+Triage the performance regression in {{scope}} over {{range}}: is it real, when did it start, who
+does it hit, and what is causing it?
+
+Work through the method below with the read-only tools it names, then answer.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first: the real scene
+   ids, the data freshness, and which metrics are empty because their capture channel is off. A
+   performance channel that was never enabled looks exactly like a scene with no problem.
+
+2. **Confirm something moved.** `insight_movers`{{#scene}} (`scene="{{scene}}"`){{/scene}} ranks
+   every comparable metric against the previous equal window by how unusual the change is. Read
+   `direction` with the sign of `delta` — a _rise_ in jank or errors is a regression — and drop any
+   row with `aboveMinSample: false`.
+
+3. **Ask whether the new level is outside normal.** `insight_baseline` on `perf_summary` gives the
+   project's own median and spread; compare the new reading with `median` give or take a few `mad`,
+   or with the p10..p90 band. Frame rates are noisy, and "down 6 FPS" is routine in some projects
+   and an incident in others.
+
+4. **Prove it rather than asserting it.** `insight_significance` on the metric that moved reports
+   the effect, a 95 % interval and a p-value across the two windows. An interval straddling 0 means
+   you cannot tell yet; `powerNote` says what this much data could have detected at all. Say "not
+   yet distinguishable from noise" when that is the truth — it is a finding.
+
+5. **Put a date on it.** `insight_anomalies` (`metric=perf_summary`, `window=28`{{#scene}},
+   `scene="{{scene}}"`{{/scene}}) separates a one-day `spike`/`drop` from a `shift` — a level that
+   changed and stayed changed, which is what a release looks like. Quote the `bucketStart` and the
+   `contributor`. For the day-by-day shape around that date, ask the `query` tool for
+   `metric: "perf_daily"` — it is a registry metric with no canned tool of its own.
+
+6. **Locate it.** `perf_by_scene` (which scene), `perf_by_device` (which device class — a
+   regression that only hits low-end hardware is a different bug from one that hits everyone), and
+   `perf_heatmap`{{#scene}} (`scene="{{scene}}"`){{/scene}} for _where in the scene_ the frames are
+   being lost. Ask for `format: "summary"` on the heatmap: merged clusters with shares, not a grid.
+
+7. **Name the mechanism.** `frame_time_percentiles` and `jank_rate` separate "uniformly slower"
+   from "occasionally catastrophic" — the second is what users report and the average hides.
+   `perf_distribution` shows whether the whole population shifted or a tail got worse.
+   `compile_stalls` finds shader/pipeline compilation blocking the first seconds.
+   `resource_percentiles` finds GPU/memory pressure. `render_scale_truth` catches a resolution
+   change quietly doing the work the frame rate is getting credit for, and `rendering_technology`
+   catches a shift in the engine/renderer mix between the two windows — a "regression" that is
+   really a change in who is measuring.
+
+8. **Cut it any way you need with the DSL.** The single `query` tool takes a `metric`, a `range`,
+   that metric's filters and `compare: { range: <the window before the shift> }`, returning
+   `{ current, previous, delta, deltaPct }` already joined — never subtract two runs yourself. Use
+   `dimensions` to regroup a portable count, `format: "summary"` for a bounded digest with a
+   `reading` and a per-row `drillQuery`, and `explain: true` whenever a number looks impossible:
+   the plan names the sample size, the row cap and every capture channel that could make it lie.
+
+## What to report
+
+- Whether the regression is real, with the effect, the interval and the honest verdict when it is
+  not yet distinguishable from noise.
+- The date it started and whether it is a spike or a sustained shift.
+- Who it hits: scene, device class, and where in the scene.
+- The mechanism, named, with the metric that shows it.
+
+Carry the caveats: percentiles below the metric's minimum sample, a session count too small to
+generalise, sampled capture (ADR 0012), truncated results, and any device class whose share of
+traffic changed between the windows — a mix shift moves the average without anything getting slower.
+
+End with 2–3 concrete recommendations naming the scene, the device class or the asset they apply
+to. If an `annotate` tool is available, leave a dated note on the shift so the next report can see
+what happened; `save_analysis` keeps the triage for the post-mortem. If a `pin_panel` tool is
+available, pin the panel that shows the regression.