@uptimizr/mcp 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Read-only Model Context Protocol (MCP) server over an Uptimizr collector's query API — let an agent ask questions of your own 3D analytics, on your own infrastructure.",
   "keywords": [
     "uptimizr",
@@ -40,6 +40,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE",
     "AGENTS.md",
@@ -48,27 +49,27 @@
   "sideEffects": false,
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.5.4",
-    "@uptimizr/agent-core": "1.1.1",
-    "@uptimizr/metrics": "0.1.0",
-    "@uptimizr/schema": "1.1.0"
+    "zod": "^4.6.5",
+    "@uptimizr/agent-core": "1.2.0",
+    "@uptimizr/metrics": "0.2.0",
+    "@uptimizr/schema": "1.2.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
-    "tsx": "^4.23.13",
-    "vitest": "^4.1.11"
+    "@types/node": "^26.6.2",
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node ../../../scripts/copy-dir.mjs ../agent-core/skills skills",
     "dev": "tsc -p tsconfig.json --watch",
     "serve": "tsx src/bin.ts",
     "start": "node dist/bin.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "lint": "eslint .",
-    "clean": "rimraf -g dist *.tsbuildinfo"
+    "clean": "rimraf -g dist skills *.tsbuildinfo"
   }
 }

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.

package/skills/weekly-scene-health/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: weekly_scene_health
+title: Weekly scene health
+description: >-
+  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. Trigger phrases: weekly report, scene health, how is
+  my scene doing, what changed this week, health check, monthly review, status report.
+tools:
+  - insight_scene_health
+  - insight_movers
+  - insight_baseline
+  - insight_significance
+  - insight_anomalies
+  - event_counts
+  - timeseries
+  - perf_summary
+  - top_meshes
+  - list_sessions
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: false
+    description: Optional scene id to scope the analysis to (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to report on, in words — e.g. "the last 7 days", "June".
+---
+
+Give me a weekly health report for {{scope}} covering {{range}}.
+
+Work through the method below with the read-only tools it names, then summarise the findings.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first: it gives the
+   real scene ids, region ids and custom-event names for this project, and tells you which metrics
+   are empty because their capture channel is off. Use its ids instead of inventing your own, and
+   never report a switched-off channel's zero as a finding.
+
+2. **Start from the score, not the numbers.** Call `insight_scene_health`{{#scene}} with
+   `scene="{{scene}}"`{{/scene}}: it scores each scene 0–100 over six weighted factors — perf
+   stability, jank, errors, dead clicks, coverage and XR abandonment — so you start from _which_
+   scene to look at. Open the lowest-scoring scene first, then the factor whose own score is
+   furthest below 50. Every factor names the `metric` behind it, its `raw` value and the project
+   `baseline` it was compared with, so the sentence you write is already in the row. 50 is the
+   project norm, not a pass mark, and a factor with `score: null` was not counted — its `note`
+   says why.
+
+3. **Find out what moved.** Call `insight_movers`{{#scene}} (`scene="{{scene}}"`){{/scene}}: it
+   compares every comparable metric with the previous equal window and ranks the changes by how
+   unusual each one is, so start from what actually moved instead of re-deriving it. Read
+   `direction` together with the sign of `delta` — a rise in a `down` metric (errors, dead clicks,
+   jank) is a regression — and do not report any row with `aboveMinSample: false`: its delta is
+   real arithmetic but not evidence.
+
+4. **Ask whether the new level is even unusual.** For each metric that moved, call
+   `insight_baseline` and compare the new value with `median` give or take a few `mad`, or with
+   the p10..p90 band. "Down 12 %" means nothing until you know the week-to-week spread.
+
+5. **Before calling any single change real, test it.** `insight_significance` reports the effect,
+   a 95 % interval and a p-value for one metric across the two windows. An interval that straddles
+   0 means you cannot tell yet, whatever the p-value says, and `powerNote` states what this much
+   data could have detected at all.
+
+6. **Put a date on it.** Call `insight_anomalies` (`metric=perf_summary`, then `error_heatmap`{{#scene}},
+   `scene="{{scene}}"`{{/scene}}, `window=28`): it returns the individual days that were out of line
+   (`spike` / `drop`) and the day a level changed and stayed changed (`shift`), with `contributor`
+   naming the mesh, channel or source holding most of the excess. Quote the `bucketStart` and the
+   `contributor` rather than saying "recently".
+
+7. **Fill in the picture.** `event_counts` for the per-event-type mix{{#scene}} (`scene="{{scene}}"`){{/scene}};
+   `timeseries` (`interval` ≈ 86400 s) for day-by-day volume and the average-FPS trend;
+   `perf_summary` for avg/min/p50 FPS; `top_meshes` for the most-interacted meshes; `list_sessions`
+   for how many sessions were recorded.
+
+8. **Drill with the DSL, not with arithmetic.** When a canned tool does not expose the filter you
+   need, use the single `query` tool: pick the `metric`, bound it with `range`, and set
+   `compare: { range: <previous week> }` so the collector returns
+   `{ current, previous, delta, deltaPct }` already joined — never run two queries and subtract
+   them yourself. `dimensions` regroups a portable count (event, mesh, input-source and gesture
+   tallies) without a new tool. Ask for `format: "summary"` on anything long or spatial: it comes
+   back as a bounded digest with shares, a plain-language `reading`, and a `drillQuery` per row you
+   can send straight back. If a result is surprising or empty, re-send it with `explain: true` and
+   read the plan before you report the number.
+
+## What to report
+
+- The score and the two or three factors that drag it down, each with the metric id behind it.
+- What moved, by how much, and whether it is outside the baseline — with the date the anomaly
+  scan put on it.
+- Traffic, event mix, FPS trend and the meshes people actually touch.
+
+Always carry the caveats into the text rather than dropping them: a row below its minimum sample
+(`aboveMinSample: false`), a metric whose capture channel the context document says is off, and any
+`meta.truncated` or `caveats` entry on a result you quoted. Say "not enough data to tell" when that
+is the honest answer.
+
+End with 2–3 concrete recommendations — each naming the scene, the mesh or the day it applies to.
+If an `annotate` tool is available, leave a dated note on the finding you want the next reader to
+see, and if `save_analysis` is available, store the report so next week's run has something to
+compare against. If a `pin_panel` tool is available, pin the panel behind the headline factor.

package/skills/xr-comfort-audit/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: xr_comfort_audit
+title: XR comfort & drop-off audit
+description: >-
+  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. Trigger phrases:
+  XR comfort, VR motion sickness, why do people quit VR, headset drop-off, teleport vs smooth
+  locomotion, guardian boundary, hand tracking vs controllers.
+tools:
+  - xr_rotation
+  - xr_locomotion
+  - xr_abandonment
+  - xr_sources
+  - xr_tracking_quality
+  - xr_boundary_contacts
+  - boundary_heatmap_stats
+  - insight_scene_health
+  - insight_movers
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: false
+    description: Optional scene id to scope the audit to (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to audit, in words — e.g. "the last 7 days", "since the XR release".
+---
+
+Audit XR/immersive comfort and drop-off for {{scope}} over {{range}}.
+
+Work through the method below with the read-only tools it names{{#scene}}, all scoped with
+`scene="{{scene}}"`{{/scene}}, and correlate the signals — no single one of them is a verdict.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first. Every metric
+   below is gated on the **XR capture channel**: if the context document says it is off, these
+   tools return empty by design and the honest answer is "XR capture is not enabled here", not
+   "there is no comfort problem".
+
+2. **Rapid head rotation — the motion-sickness proxy.** `xr_rotation`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   gives the rate of fast head/view turns. High rates are a proxy, not a diagnosis: they can mean
+   discomfort-inducing camera work, or simply a scene that rewards looking around. Read it against
+   the next two signals before calling it.
+
+3. **Locomotion style and session span.** `xr_locomotion`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   gives the fly / navigate / teleport mix and how long each session lasted. Continuous (smooth)
+   locomotion paired with heavy rapid rotation is the classic uncomfortable combination; teleport
+   is the usual mitigation.
+
+4. **Did they take the headset off?** `xr_abandonment`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   finds immersive sessions that ended early. Early exits _plus_ one of the two signals above is
+   the finding; early exits on their own may just be a short demo.
+
+5. **Rule out the boring explanations first.** `xr_tracking_quality` catches tracking loss — an
+   exit caused by the headset losing its pose is not a comfort problem.
+   `xr_boundary_contacts` and `boundary_heatmap_stats` catch a play space that is too small or a
+   scene that pushes people into the guardian; that is a layout problem with a layout fix.
+
+6. **Who is playing.** `xr_sources`{{#scene}} (`scene="{{scene}}"`){{/scene}} gives the hand vs.
+   controller vs. gaze input split. Comfort conclusions differ by input source, and a shift in the
+   mix between two windows can move every other number without anything getting worse.
+
+7. **Put it in context.** `insight_scene_health` scores XR abandonment as one of its six weighted
+   factors, so it tells you whether this scene is unusual _for this project_;
+   `insight_movers`{{#scene}} (`scene="{{scene}}"`){{/scene}} tells you whether the comfort signals
+   moved against the previous equal window. Drop any row with `aboveMinSample: false`.
+
+8. **Cut it further with the DSL.** The single `query` tool takes a `metric`, a `range`, that
+   metric's filters, `dimensions` to regroup a portable count, and `compare: { range: <previous
+window> }` for `{ current, previous, delta, deltaPct }` already joined. `format: "summary"`
+   returns a bounded digest with a plain-language `reading`; `explain: true` returns the plan
+   instead of the rows and names every reason the answer might mislead — worth one call before
+   reporting a zero on a channel-gated metric.
+
+## What to report
+
+- The uncomfortable patterns you can actually evidence: heavy rapid rotation or continuous
+  locomotion paired with early exits, named per scene and per input source.
+- The alternatives you ruled out: tracking loss, boundary contacts, a short-by-design experience.
+- Comfort mitigations: teleport or snap-turn options, vignetting during movement, slower or
+  user-controlled camera motion, a larger required play space, or moving interactive content
+  inside the guardian.
+
+Carry the caveats: XR sessions are a small fraction of most projects' traffic, so say the session
+count next to every rate; the rotation and locomotion metrics are sampled (ADR 0012); and a metric
+whose channel is off is not a zero. Never turn one uncomfortable session into a trend.
+
+End with 2–3 concrete comfort changes, each tied to the scene and the locomotion or input mode it
+applies to. If an `annotate` tool is available, leave a note on the scene so the next audit can see
+what was tried; `save_analysis` keeps the before-picture to compare the fix against. If a
+`pin_panel` tool is available, pin the locomotion-comfort panel.