Refresh Replay Vision docs for current product state

contents/docs/replay-vision/creating-scanners.mdx

@@ -79,7 +79,9 @@ A prompt that reads beautifully on its own can still misfire. The fastest feedba
 4. Adjust the prompt where the model misread something obvious.
 5. Scan another batch of recordings and repeat until the results look right.
 
-Hold off on the automatic background sweep until you trust the scanner's on-demand results – every sweep observation counts against your [monthly quota](/docs/replay-vision/quota-and-limits), and a poorly tuned scanner can burn through it fast on results you'd throw away anyway.
+Hold off on the automatic background sweep until you trust the scanner's on-demand results – every sweep observation costs [budget](/docs/replay-vision/quota-and-limits), and a poorly tuned scanner can burn through it fast on results you'd throw away anyway.
+
+Once the scanner is running, the tuning loop moves to its [quality tab](/docs/replay-vision/quality): rate results with a thumbs up or down, and PostHog AI turns your team's ratings and feedback into configuration recommendations you can test against the rated sessions before applying.
 
 ### Drafting prompts with PostHog AI
 
@@ -95,11 +97,13 @@ Inside the scanner editor, you can ask [PostHog AI](/docs/posthog-ai) to draft a
 
 Each scanner type has a few extra knobs. The full reference is on the [scanner types](/docs/replay-vision/scanner-types) page; the highlights:
 
-- **Classifier** – define your tag vocabulary, choose whether multiple tags per session are allowed, and whether the model can invent tags outside the vocabulary.
+- **Classifier** – define your tag vocabulary (or have PostHog AI suggest tags based on your prompt and what's been seen in recordings), choose whether multiple tags per session are allowed, and whether the model can invent tags outside the vocabulary.
 - **Scorer** – set the numeric scale (min, max) and an optional label describing what the scale means.
-- **Summarizer** – pick a summary length (short / medium / long).
+- **Summarizer** – pick a summary length (short / medium / long). The core summarizer prompt is built in, so the prompt field becomes **Additional context**: use it for product context or steering, like what the ideal user flow looks like.
 - **Monitor** – choose whether the model can return `inconclusive` rather than forcing a yes/no answer.
 
+The editor also has a **model** picker. Newer models tend to produce higher-quality observations but cost more per observation – each option shows its price, and the [budget](/docs/replay-vision/quota-and-limits) page explains how costs add up.
+
 ## Filters: scoping the scanner
 
 Recording filters use the same query builder as the rest of [Session Replay](/docs/session-replay/how-to-control-which-sessions-you-record). You can filter by:
@@ -111,47 +115,48 @@ Recording filters use the same query builder as the rest of [Session Replay](/do
 
 A scanner with no filters matches every eligible session in your project. A scanner with narrow filters – e.g. "sessions on `/checkout` longer than 30 seconds for users on the trial plan" – is much cheaper, much faster to iterate on, and usually more useful.
 
+One limit applies regardless of filters: recordings with more than 1 hour of active interaction take too long to analyze well, so Vision always skips them.
+
 A good default discipline: start with a narrow filter while you're tuning the prompt, then widen the filter once you trust the results.
 
 ## Session coverage: filtering by quality
 
-The **Session coverage** toggle pre-filters recordings by their predicted quality before sampling is applied. It uses an internally-computed surfacing score that estimates how much meaningful activity a recording contains – engagement, errors, navigation – versus idle or empty sessions.
+The **Session coverage** setting pre-filters recordings by their activity level before sampling is applied. It uses an internally-computed relevance score that estimates how much meaningful activity a recording contains – engagement, errors, navigation – versus idle or empty sessions.
 
-| Mode              | What it keeps                                    |
-| ----------------- | ------------------------------------------------ |
-| **Focused**       | Roughly the top 25% of sessions by quality score |
-| **Balanced**      | Roughly the top 65% of sessions by quality score |
-| **Comprehensive** | All sessions – no quality filtering (default)    |
+| Mode                      | What it keeps                                      |
+| ------------------------- | -------------------------------------------------- |
+| **Highest activity only** | Roughly the top 25% of sessions by activity score  |
+| **Skip lowest activity**  | Roughly the top 65% of sessions by activity score  |
+| **All recordings**        | Every session matching your filters (default)      |
 
-Sessions without a score are skipped by Focused and Balanced modes.
+Sessions without a score are skipped by the two filtered modes.
 
 The three-step filtering process is:
 
 1. **Recording filters** pick sessions matching your criteria.
-2. **Session coverage** drops low-quality sessions by surfacing score.
+2. **Session coverage** drops low-activity sessions by relevance score.
 3. **Sampling rate** randomly keeps a fraction of what's left.
 
-Existing scanners default to Comprehensive, so they behave the same as before.
-
-Use a tighter coverage mode when you want to spend your observation budget on sessions where something actually happened, rather than idle or empty recordings.
+Use a tighter coverage mode when you want to spend your budget on sessions where something actually happened, rather than idle or empty recordings.
 
 ## Sampling rate: controlling volume
 
 The sampling rate (0–100%) is applied **after** the filters match. A scanner with filter "sessions over 30 seconds" and sampling 25% scans roughly one in four of those sessions.
 
-The scanner editor shows a **per-month estimate** of how many observations the scanner will produce, based on your project's recent recording volume, the filters you've set, the session coverage mode, and the sampling rate. Use this to size the scanner against your [quota](/docs/replay-vision/quota-and-limits) _before_ saving.
+The scanner editor shows an **estimated cost** – roughly how many observations the scanner will produce per month and what they'll cost at the selected model's price – based on your project's recent recording volume, the filters you've set, the session coverage mode, and the sampling rate. Use this to size the scanner against your [budget](/docs/replay-vision/quota-and-limits) _before_ saving.
 
 <ProductScreenshot
   imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/estimate_callout_2d954ec2cb.png"
   alt="The scan conditions step of the scanner editor: sampling rate, recording filters, and the estimated per-month impact against the remaining quota"
   classes="rounded"
 />
 
-If the estimate looks too high, you have three knobs:
+If the estimate looks too high, you have four knobs:
 
 - Narrow the filters.
-- Tighten the session coverage mode (Comprehensive → Balanced → Focused).
+- Tighten the session coverage mode (All recordings → Skip lowest activity → Highest activity only).
 - Lower the sampling rate.
+- Pick a cheaper model.
 
 ## Enabling and disabling
 
@@ -163,7 +168,7 @@ To stop a scanner entirely, delete it. Deleting a scanner also removes all of it
 
 ## Handing off to Responder agents
 
-Each scanner has a **Hand off to Responder agents** toggle in the configuration step. When enabled, the scanner gains a side mission: during each scan, the model looks for clear, actionable product issues – bugs, broken or confusing flows, errors, or significant UX friction – and reports them as findings.
+Each scanner has an **Emit findings as Signals** toggle in the editor's self-driving step. When enabled, the scanner gains a side mission: during each scan, the model looks for clear, actionable product issues – bugs, broken or confusing flows, errors, or significant UX friction – and reports them as findings.
 
 The scanner's primary task (monitoring, classifying, scoring, or summarizing) is unaffected. The side mission runs alongside it, and most scans produce no finding at all. The bar is deliberately high: a finding must be self-contained and concrete enough for someone with no session context to act on it.
 

contents/docs/replay-vision/index.mdx

@@ -56,6 +56,7 @@ Each of these maps to a [scanner type](/docs/replay-vision/scanner-types).
 - **Picking the right scanner type?** Read the [scanner types reference](/docs/replay-vision/scanner-types).
 - **Authoring a scanner?** See [creating scanners](/docs/replay-vision/creating-scanners) for prompt patterns, filters, and sampling.
 - **Already have observations?** Learn how to [read them and query them as events](/docs/replay-vision/observations) to build insights, dashboards, and alerts.
+- **Is the scanner getting it right?** Rate results and apply AI configuration recommendations on the [quality tab](/docs/replay-vision/quality).
 - **Hit a snag?** Check [troubleshooting](/docs/replay-vision/troubleshooting).
 
 ## Further reading

contents/docs/replay-vision/mcp.mdx

@@ -33,8 +33,8 @@ Replay Vision's MCP tools are all prefixed `vision-`. They fall into a few group
 
 ### Sizing before you create
 
-- `vision-scanners-estimate-create` – project the per-month observation volume of a hypothetical scanner before you commit to it.
-- `vision-quota-retrieve` – check the remaining monthly quota.
+- `vision-scanners-estimate-create` – project the per-month observation volume and cost of a hypothetical scanner before you commit to it.
+- `vision-quota-retrieve` – check the remaining monthly budget.
 
 Pair these two before calling `vision-scanners-create` to avoid creating a scanner that would immediately blow the budget.
 
@@ -56,6 +56,18 @@ For one scanner (across sessions):
 - `vision-scanners-observations-list` – paginated list of a scanner's observations.
 - `vision-scanners-observations-get` – fetch one of that scanner's observations by ID.
 
+### Rating results and improving the scanner
+
+The [quality tab](/docs/replay-vision/quality)'s loop is fully drivable over MCP:
+
+- `vision-observations-label-create` – rate an observation with a thumbs up or down, optionally with written feedback. Same rating the Quality tab records.
+- `vision-observations-label-destroy` – remove a rating.
+- `vision-scanners-observations-stats` – rating counts over time and per configuration version.
+- `vision-scanners-prompt-suggestions-generate` – generate a configuration recommendation from the team's ratings.
+- `vision-scanners-prompt-suggestions-current` – read the current recommendation.
+- `vision-scanners-prompt-suggestions-apply` – apply it to the scanner as a new version.
+- `vision-scanners-prompt-suggestions-dismiss` – dismiss it.
+
 ### Impact and cohorts
 
 - `vision-scanners-impact-retrieve` – get affected sessions and users for a scanner over a trailing window. Monitors count verdict-yes observations. Classifiers require a `tag` parameter. Scorers require `min_score` and/or `max_score`.
@@ -71,7 +83,9 @@ Try these with your MCP-enabled agent:
 - `Scan session abc123 with the "Dead-end pages" scanner and tell me what it found, including the reasoning.`
 - `List the last 20 observations from my "Frustration score" scanner and summarize what's driving high scores.`
 - `Find every Replay Vision observation for session abc123 and give me a one-line summary of each.`
-- `How much Replay Vision quota do we have left this month?`
+- `How much Replay Vision budget do we have left this month?`
 - `How many users did my "Dead-end pages" monitor affect in the last 14 days? Save them as a cohort.`
+- `Look at the last 10 observations from my "Dead-end pages" scanner, rate each one right or wrong based on the reasoning, and leave feedback on the wrong ones.`
+- `Generate a configuration recommendation for my "User intent" classifier from the team's ratings and show me what it would change.`
 
 See the [MCP server docs](/docs/model-context-protocol) for client setup, and the [Replay Vision overview](/docs/replay-vision) for product concepts.

contents/docs/replay-vision/observations.mdx

@@ -14,6 +14,8 @@ Each scanner has an **Observations** tab listing every observation it's produced
 
 Observations also surface in the replay player: the **observations dock** at the bottom of the player lists everything scanners have found about the session you're watching, and is where the **Scan this recording** action lives.
 
+To judge whether the results are right – and improve the scanner from that judgment – rate observations on the scanner's [quality tab](/docs/replay-vision/quality).
+
 <ProductScreenshot
   imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/observations_dock_0301561e5d.png"
   alt="The replay player with the observations dock expanded, listing observation cards from several scanners and the Scan this recording action"
@@ -28,7 +30,7 @@ Observations move through a small state machine:
 - **`failed`** – terminal. The detail view shows an error reason. See [troubleshooting](/docs/replay-vision/troubleshooting#failed-observations) for what each failure kind means.
 - **`ineligible`** – terminal. The session can't be analyzed (no recording, too short, no events, etc.). Doesn't count against your quota. See [running scanners](/docs/replay-vision/running-scanners#ineligible-sessions).
 
-Succeeded, pending, and running observations count against your monthly [quota](/docs/replay-vision/quota-and-limits); failed and ineligible ones don't.
+Succeeded, pending, and running observations count against your monthly [budget](/docs/replay-vision/quota-and-limits); failed and ineligible ones don't.
 
 ## Querying observations as events
 
@@ -47,6 +49,7 @@ Every successful observation is captured as a `$recording_observed` event in you
 | `triggered_by_user_id`           | The user who triggered an on-demand observation; null for background sweeps                                                                         |
 | `model_used`                     | The model that produced the result                                                                                                                  |
 | `provider_used`                  | The LLM provider behind `model_used`                                                                                                                |
+| `credits`                        | What this observation cost, in credits (100 credits = $1), frozen at the price when it ran                                                          |
 | `scanner_output_confidence`      | The model's confidence (0.0 to 1.0)                                                                                                                 |
 | `scanner_output_reasoning`       | **Monitor, classifier, and scorer** – the model's reasoning text, including any inline citations. Summarizers don't have a separate reasoning field |
 | `scanner_output_verdict`         | **Monitor only** – `"yes"`, `"no"`, or `"inconclusive"`                                                                                             |
@@ -176,6 +179,21 @@ GROUP BY friction_point
 ORDER BY sessions DESC
 ```
 
+### Cross-scanner: spend by scanner
+
+Each event carries a `credits` property with the observation's cost (100 credits = $1), so spend is just another query. This is the same data behind the **Usage** tab on the Replay Vision home:
+
+```sql
+SELECT
+    properties.scanner_name AS scanner,
+    sum(toFloat64(properties.credits)) / 100 AS dollars
+FROM events
+WHERE event = '$recording_observed'
+  AND timestamp > now() - INTERVAL 30 DAY
+GROUP BY scanner
+ORDER BY dollars DESC
+```
+
 ### Cross-scanner: filter only high-confidence verdicts
 
 ```sql
@@ -190,7 +208,7 @@ Confidence is self-reported, so this is a heuristic, not a guarantee – but it'
 
 ## Scanner impact and cohorts
 
-Each scanner tracks its impact: how many sessions and users its findings affected over a trailing window (default 30 days). These counts appear in the scanner overview panel.
+Each scanner tracks its impact: how many sessions and users its findings affected over a trailing window (default 30 days). These counts appear on the scanner's **Overview** tab.
 
 What counts as "affected" depends on the scanner type: