Subtext

View saved version →

---
name: subtext-privacy
description: Privacy rule management — detect PII in sessions and manage element-block, URL, and network privacy rules. Use when you need to propose, create, list, delete, or promote privacy rules for a Fullstory org.
---

# Privacy

> **PREREQUISITE:** Read `subtext-shared` for MCP conventions.

Privacy tools manage three kinds of rules that control what Fullstory session recordings capture:

- **Element rules** — CSS-selector-based rules that mask or exclude specific page elements.
- **URL rules** — scrub sensitive parts of captured URLs (host/path/query).
- **Network rules** — control whether request/response bodies are captured, redacted, or partially allowlisted.

## MCP Tools

| Tool | Description |
|------|-------------|
| `privacy-propose` | Scan a session for PII and return suggested selectors (dry-run — persists nothing). Element rules only. |
| `privacy-create` | Create element-block rules from selectors in preview scope. |
| `privacy-list` | List existing element-block rules, with optional scope/type filters. |
| `privacy-delete` | Delete preview-scoped rules by ID. |
| `privacy-promote` | Promote preview-scoped rules to apply to all sessions. |
| `privacy-url-list` | List URL privacy rules. |
| `privacy-url-create` | Create a URL privacy rule that scrubs host/path/query, or update one in place by passing `guid`. Live immediately. |
| `privacy-network-list` | List network (request/response body) privacy rules. |
| `privacy-network-create` | Create a network privacy rule (elide or allowlist body fields), or update the existing rule for a `url_regex` by passing `overwrite=true`. Live immediately. |

Listing and creation are supported for all three rule kinds. There's no separate update tool for URL/network rules — `privacy-url-create`/`privacy-network-create` double as update when you pass `guid`/`overwrite`. Deletion is only supported for element rules today.

## Rule lifecycle (element rules)

Rules always start in **preview scope** (`PREVIEW_SESSIONS_ONLY`) and must be explicitly promoted to apply broadly:

```
propose (dry-run)
    │
    ▼
create → PREVIEW_SESSIONS_ONLY
    │
    ▼
list / verify
    │
    ▼
promote → ALL_SESSIONS
    │        ─ or ─
    ▼
delete (preview only)
```

## URL and network rules: no preview step

Unlike element rules, **URL and network rules have no scope and no preview/promote lifecycle.** `privacy-url-create` and `privacy-network-create` take effect for **all sessions immediately** — there is nothing to promote, and (for now) nothing to delete via MCP. Double-check a rule before creating it; use `privacy-url-list` / `privacy-network-list` afterward to confirm what's live.

### URL rules

`privacy-url-create` takes a `name` plus either simplified fields or a raw `advanced` override:

```
privacy-url-create name="scrub-ssn-param" match_host="example\.com" exclude_query_params=["ssn"]
```

This redacts the `ssn` query parameter's value (not its key) on URLs whose host matches `example\.com`. Leave `match_host`/`match_path` both empty for an unconditional rule (applies to every URL). Use `exclude_path` / `exclude_query` for a raw regex against the path or full query string instead of a named param. Use `advanced` (structured `if`/`exclude` pattern sets over hash/host/path/query_param/query) only when the simplified fields can't express the rule.

**Updating a URL rule:** pass the rule's `guid` (from `privacy-url-list`) to replace it in place instead of creating a new one:

```
privacy-url-create guid="<guid>" name="scrub-ssn-param" match_host="example\.com" exclude_query_params=["ssn", "token"]
```

Update is a **full replace**, not a merge — pass the complete desired state (name, condition, exclusions), not just the field you're changing. Built-in rules (part of the default rule set created at privacy settings setup) cannot be updated this way.

### Network rules

`privacy-network-create` takes a `url_regex` plus request/response body handling:

```
privacy-net

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: subtext-review
description: Review a completed Subtext session and produce a structured summary. Use when you have a session URL and want to understand what happened — verify a flow, walk through a dev / staging / preview session, or summarize a captured session. Optionally emits reproduction steps on request.
---

# Review

> **PREREQUISITE:** Read `subtext-shared` and `subtext-session` for tool conventions.

**Type:** Workflow — goal-oriented with decision logic.

Review a completed session and produce a structured summary of what happened. Optionally emit reproduction steps when the user asks. Review is read-only analysis.

## When to use

**Use when:**
- The user provides a session URL and wants to know what happened.
- The user asks for a walkthrough, summary, or diagnosis of a session.
- Session source is any of: local dev, staging, preview, production.

**Skip when:**
- The user wants the repro *executed*, not just described — that needs a live browser (the separate Subtext Verify plugin).

## The loop

### Step 1: Open the session

Call `review-open` with whichever identifier you have — see `subtext-session` for the six accepted forms. Capture the `client_id` from the response, and read the **map** it returns — signal counts by kind/tag and page flow. Don't call `review-zoom` yet.

### Step 2: Form hypotheses from the map

The map is the orientation layer. Before zooming, ask: does anything in `kinds`/`tags` stand out (an `error:` count, an unusually dense phase)? Form one or two hypotheses about what happened — that's what you zoom to confirm.

### Step 3: Zoom to confirm — as recipes, coarse to fine

Use `review-zoom` with a `resolution` map. Treat resolutions as recipes, not parameters to memorize:

- Errors anywhere → `resolution={ error: "standard" }`
- What happened overall → `resolution={ navigation: "standard", interaction: "standard" }`
- Devtool-level detail on a suspect window → `resolution={ network: "machine", console: "machine" }`, narrowed with `t0_ms`/`t1_ms`

Start coarse (`standard`, the default) and only reach for `machine`/`detail` on the specific kind or tag your hypothesis needs — each step down costs more tokens for more fidelity. Judge coverage against the map from `review-open` (its `kinds`/`tags` counts); `review-zoom` returns the signal slice.

When you need to see the screen itself — confirm a layout, grab a component tree — use `review-snapshot` at the timestamp in question. It's a separate data set from signals; don't expect it to carry network/console detail.

Don't sweep the entire session frame-by-frame — that's expensive and usually unnecessary. Lead with the map and the errors it surfaces.

### Step 4: Assess

Form a judgment on:

- **What the session was trying to accomplish** — inferable from behavior.
- **Did it succeed** — any errors? Did the final state match the apparent intent?
- **Notable moments** — anything surprising, confusing, or worth flagging to the user.

### Step 5: Produce the structured summary

Output in this shape — stable sections make the result easy to consume, especially for a downstream agent:

```markdown
## Session Summary

**Session:** <URL>
**Type:** <dev | staging | preview | production>
**Duration:** <if available>

### What happened
<One-paragraph narrative of what the user/agent tried to do.>

### Errors
<Timestamped list with context, or: "None observed.">

### Key moments
- `<timestamp>` — <inflection point>

### Assessment
<One paragraph. Did the session achieve its apparent goal? Anything the next reader should know?>
```

### Step 6: Reproduction steps — only if asked

If the user explicitly asks to reproduce, append a structured step list. **Do not execute** — this plugin is read-only. Executing a repro requires driving a live browser, which lives in the separate Subtext Verify plugin.

```markdown
### Reproduction steps

1. Navigate to <URL>
2. <action> — e.g., "Click the 'Sign in' button"
3. <observation to confirm> — e.g., "Verify m

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: subtext-session
description: Session replay tools for analyzing Fullstory session recordings. Sparse API catalog — tools are self-describing.
---

# Session Replay

> **PREREQUISITE:** Read `subtext-shared` for MCP conventions.

API catalog for the session replay tools (all prefixed `review-`). One gesture — **zoom** — over two data sets: the **signal stream** (temporal) and the **snapshot** (spatial). Opening a session hands back a **map**: an always-on orientation header, never a zoom level.

## MCP Tools

| Tool | Description |
|------|-------------|
| `review-list-sessions` | Find reviewable sessions — numbered URLs + timestamps. |
| `review-open` | Open a session for analysis. Returns a handle (`client_id`) plus the **map** and a digest rollup. |
| `review-summary` | Static "what happened" — the default zoom (all kinds @ `standard`), frozen. No map, no handle. Stateless, cheapest call. Use for a quick read before deciding whether to `open`. |
| `review-zoom` | The live lens. Pass a `resolution` map and/or a `t0_ms`/`t1_ms` time window — returns the matching signal slice. |
| `review-snapshot` | The screen at a moment — screenshot + component tree + boxes, rooted at an optional `component_id`. |
| `review-close` | Close the session and free resources; records a short usage summary. |

## Discovering Parameters

Parameter schemas are visible in the tool definition at call time.

## Session Input

`review-open` accepts six mutually-exclusive identifiers. Pick the one that matches what you have on hand — they're all first-class:

- `session_url` — a full Fullstory session URL. The most common form — a customer-shared link, a Slack paste, or a session from the app UI.
- `trace_id` — the 12-char base62 id from a prior `review-open` response.
- `trace_url` — a full trace URL copied from the browser or returned by a live tool.
- `device_id` + `session_id` — both required together. Use when you have the raw ids but no URL.
- `email_address` / `user_uid` — looks up the user's most recent session.

All six paths return the same handle. Capture the `client_id` from the response so follow-on `review-zoom`/`review-snapshot`/`review-close` calls don't need to re-resolve the session.

## The map

`review-open`'s response includes a map — a cheap counting fold over the signal layer, never a body dump:

```
## Map · 114 signals · 0.0s–353s · 2 pages
flow: /ui ▸ /settings/overview ▸ /subtext/sessions ▸ /subtext/session/asr
kinds: navigation 18 · interaction 36 · network 58 (2 err) · console 2 (2 err)
tags: error:4
```

The map is **whole** — rendered once, over the entire session. Zooming into `{navigation: "standard"}` later doesn't touch it: `error:4` stays in the map's counts regardless of what you go on to zoom into. Read the map first; it tells you what exists before you pay for a zoom.

## The resolution contract

`review-zoom` takes:

```
resolution?: { [scope | kind | tag]: "digest" | "standard" | "machine" | "detail" }
t0_ms?: number   // narrow the zoom to a time window
t1_ms?: number
```

Grain ladder, coarse → fine:

| grain | what you see |
|-------|--------------|
| `digest` | one rollup line per (section × kind) — `network ×19 (1 err)` |
| `standard` *(default)* | the readable transcript — bursty/repeated signals merged into one line |
| `machine` | every signal, nothing merged |
| `detail` | every signal plus its payload — headers, bodies, stack traces |

- **Omit `resolution`** → everything at `standard`.
- **Provide it** → an explicit allow-list. Unlisted kinds are excluded from the slice (never from the map).
- **Overlap → finest-wins.** A signal matching more than one key takes the finest grain among them — order-independent, and it can only ever show *more*, never hide something.

Keys are scopes (`navigation`, `interaction`, `network`, `console`, …), kinds (`click`, `network`, `exception`, …), or tags (`error`, `exception` — the only tags today) — they resolve the same way.

### Zoom recipes

```
// what went

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: subtext-shared
description: Foundation skill for the Subtext plugin. MCP tool conventions and security rules. Read this when any skill lists it in PREREQUISITE.
---

# Shared

Foundation for all Subtext skills. Read this when a skill lists it in PREREQUISITE.

## MCP Servers

All tools are served from the **subtext** MCP server. A **subtext-eu1** variant exists for EU1 data center sessions (`app.eu1.fullstory.com`). The agent framework resolves tool prefixes automatically based on the configured MCP servers — you do not need to hardcode prefixes.

## Tool Name Prefixes

| Prefix | Tools |
|--------|-------|
| `review-` | Session replay: `review-list-sessions`, `review-open`, `review-summary`, `review-zoom`, `review-snapshot`, `review-close` |
| `privacy-` | Privacy rules: `privacy-propose`, `privacy-create`, `privacy-list`, `privacy-delete`, `privacy-promote`, `privacy-url-list`, `privacy-url-create`, `privacy-network-list`, `privacy-network-create` |
| `telemetry-` | Workflow telemetry: `telemetry-event` |

## Discovering MCP Tool Parameters

Each MCP tool is self-describing. If you're unsure about parameters, the tool's schema is available at call time. Don't memorize parameter lists — consult the atomic skill (`subtext-session` or `subtext-privacy`) for which tools exist, then let the schema guide parameter usage.

## Security Rules

- Never expose API tokens, session tokens, or credentials in output.
- Confirm with the user before any write operation that modifies org configuration (e.g. `privacy-promote`, `privacy-create`, `privacy-url-create`, `privacy-network-create`).
- Session URLs may contain sensitive user data — don't log or repeat them unnecessarily.

View saved version →

---
name: subtext-telemetry
description: Workflow telemetry logging — record AI-reported workflow milestones (currently the onboarding flow) for funnel analysis. Use when executing an instrumented Subtext workflow and you need to log step-by-step progress events.
---

# Telemetry

> **PREREQUISITE:** Read `subtext-shared` for MCP conventions.

The telemetry tool records workflow milestones to Fullstory's analytics backend (BigQuery) for funnel analysis and success-rate dashboards. It writes analytics events only — it never modifies application data or org configuration.

## MCP Tools

| Tool | Description |
|------|-------------|
| `telemetry-event` | Log one workflow milestone: a `workflow` + `step`, an optional `outcome`, and optional step-specific `metadata`. |

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `workflow` | yes | Workflow name. Currently only `onboard` (the Subtext capture-snippet install flow) is supported. |
| `step` | yes | Milestone within the workflow. For `onboard`, in order: `start`, `precheck`, `explore`, `plan`, `install`, `identify`, `link_analytics`, `mask_pii`, `complete`. |
| `outcome` | no | `success`, `partial`, `fail`, or `skipped`. Omit for in-progress milestones. |
| `metadata` | no | A JSON **object** (not an array or scalar) of step-specific fields — see below. |

## Metadata fields by step

Every step's metadata may include `duration_ms` (int) and `tokens` (int). Additional fields vary by step:

| Step | Extra fields |
|------|--------------|
| `start` | `harness` (string), `model` (string) |
| `precheck` | `already_installed` (bool) |
| `explore` | `framework` (string), `csp_present` (bool) |
| `plan` | `approved` (bool) |
| `install` | `framework` (string), `csp_modified` (bool) |
| `identify` | `identity_added` (bool) |
| `link_analytics` | `analytics_providers` (string[]) — names of every analytics / session-replay / error-monitoring / feature-flag SDK found installed, e.g. `["posthog", "segment", "sentry"]` |
| `mask_pii` | `masked_count` (int), `privacy_check` (bool) |
| `complete` | `total_duration_ms` (int), `total_tokens` (int) |

Unknown metadata fields are tolerated (ignored, not errors), but stick to the documented fields — only they land in typed columns for analysis.

## Typical flow

Log an event at each milestone as you execute the workflow, not retroactively at the end:

```
telemetry-event workflow="onboard" step="start" metadata={"harness": "claude-code", "model": "claude-fable-5"}
...
telemetry-event workflow="onboard" step="install" outcome="success" metadata={"framework": "nextjs", "csp_modified": false, "duration_ms": 42000}
...
telemetry-event workflow="onboard" step="complete" outcome="success" metadata={"total_duration_ms": 310000, "total_tokens": 85000}
```

The response is `{"logged": true}` on success or `{"logged": false, "reason": "..."}` on a soft failure.

## Rules and constraints

- **Fire-and-forget.** A `{"logged": false, ...}` response is a soft failure — note it and move on. Never retry in a loop, and never block or abort the user's workflow because telemetry failed.
- Org and user identity are attached server-side from the authenticated MCP session — don't put emails, org IDs, or other identifying data in `metadata`.
- Don't put secrets, tokens, file contents, or free-form user data in `metadata` — only the documented derived fields.
- `outcome` is a classification of the step, not a log level: use `skipped` when a step didn't apply, `partial` when it half-worked, and omit it entirely for a step that's still in progress.
- Only log events for workflows you are actually executing. The tool exists to measure real funnels — don't emit synthetic or exploratory events against a production org.

## Gotchas

- Passing `metadata` as anything other than a JSON object — arrays, strings, and scalars are rejected with `{"logged": false}`.
- Inventing workflow or step names — only `onboard` and its nine documented st

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: subtext-using-subtext
description: Overview of the Subtext plugin — when to reach for session review vs privacy tools. Read to orient before reviewing a Fullstory session or managing privacy rules.
---

# Using Subtext

This plugin gives you read-only access to Fullstory session recordings, plus privacy-rule management.

## When to reach for what

| Signal | Skill |
|--------|-------|
| You have a session URL / want to know what happened | `subtext-review` |
| You need the session-replay tool catalog (`review-*`) | `subtext-session` |
| Detect PII or manage element-block, URL, or network privacy rules | `subtext-privacy` |
| Log workflow milestones (e.g. onboarding progress) for analytics | `subtext-telemetry` |

## Notes

- Everything here is read-only analysis **except** `privacy-create` / `privacy-promote` / `privacy-delete` / `privacy-url-create` / `privacy-network-create`, which modify org privacy rules — confirm with the user first. (`telemetry-event` writes analytics events only, never org configuration — no confirmation needed.)
- This plugin does **not** drive a live browser or capture before/after proof of code changes. That lives in the separate **Subtext Verify** plugin.