Update to Subtext

{
  "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.",
  "included_files": [],
  "skill_md_contents": "---\nname: subtext-privacy\ndescription: 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.\n---\n\n# Privacy\n\n> **PREREQUISITE:** Read `subtext-shared` for MCP conventions.\n\nPrivacy tools manage three kinds of rules that control what Fullstory session recordings capture:\n\n- **Element rules** — CSS-selector-based rules that mask or exclude specific page elements.\n- **URL rules** — scrub sensitive parts of captured URLs (host/path/query).\n- **Network rules** — control whether request/response bodies are captured, redacted, or partially allowlisted.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `privacy-propose` | Scan a session for PII and return suggested selectors (dry-run — persists nothing). Element rules only. |\n| `privacy-create` | Create element-block rules from selectors in preview scope. |\n| `privacy-list` | List existing element-block rules, with optional scope/type filters. |\n| `privacy-delete` | Delete preview-scoped rules by ID. |\n| `privacy-promote` | Promote preview-scoped rules to apply to all sessions. |\n| `privacy-url-list` | List URL privacy rules. |\n| `privacy-url-create` | Create a URL privacy rule that scrubs host/path/query, or update one in place by passing `guid`. Live immediately. |\n| `privacy-network-list` | List network (request/response body) privacy rules. |\n| `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. |\n\nListing 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.\n\n## Rule lifecycle (element rules)\n\nRules always start in **preview scope** (`PREVIEW_SESSIONS_ONLY`) and must be explicitly promoted to apply broadly:\n\n```\npropose (dry-run)\n    │\n    ▼\ncreate → PREVIEW_SESSIONS_ONLY\n    │\n    ▼\nlist / verify\n    │\n    ▼\npromote → ALL_SESSIONS\n    │        ─ or ─\n    ▼\ndelete (preview only)\n```\n\n## URL and network rules: no preview step\n\nUnlike 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.\n\n### URL rules\n\n`privacy-url-create` takes a `name` plus either simplified fields or a raw `advanced` override:\n\n```\nprivacy-url-create name=\"scrub-ssn-param\" match_host=\"example\\.com\" exclude_query_params=[\"ssn\"]\n```\n\nThis 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.\n\n**Updating a URL rule:** pass the rule's `guid` (from `privacy-url-list`) to replace it in place instead of creating a new one:\n\n```\nprivacy-url-create guid=\"<guid>\" name=\"scrub-ssn-param\" match_host=\"example\\.com\" exclude_query_params=[\"ssn\", \"token\"]\n```\n\nUpdate 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.\n\n### Network rules\n\n`privacy-network-create` takes a `url_regex` plus request/response body handling:\n\n```\nprivacy-network-create url_regex=\"/api/checkout/.*\" request_body=\"whitelist\" request_allowlist_fields=[\"order_id\", \"status\"]\n```\n\nOnly `elide` (default, redact the whole body) and `whitelist` (keep only named fields) are supported for automated creation/update — `record` (capture the full body) increases data capture and must be set up manually. Rules are keyed by `url_regex`; without `overwrite`, creating a rule for a regex that already has one is a no-op.\n\n**Updating a network rule:** pass `overwrite=true` to replace the existing rule for that `url_regex` instead of skipping it:\n\n```\nprivacy-network-create url_regex=\"/api/checkout/.*\" request_body=\"whitelist\" request_allowlist_fields=[\"order_id\", \"status\", \"total\"] overwrite=true\n```\n\n## Rules and constraints\n\n- `privacy-propose` is always a **dry-run**. It returns suggested selectors but persists nothing. Use it to preview before committing.\n- `privacy-create` only supports `mask` and `exclude` block types. Unmask rules cannot be created via this tool.\n- `privacy-delete` only accepts preview-scoped rules. Promoted rules cannot be deleted here.\n- `privacy-promote` also rejects unmask rules — only mask and exclude rules can be promoted.\n- System-managed rules (not user-created) are hidden by default. Pass `include_system=true` to `privacy-list` to see them. These rules cannot be deleted or promoted.\n- `privacy-url-create` and `privacy-network-create` rules go live for all sessions immediately — there's no preview scope to validate in first.\n- `privacy-network-create` rejects `record` for request/response body mode; only `elide` and `whitelist` are allowed.\n- Neither URL nor network rules currently support deletion via MCP — use the Fullstory settings UI if a rule needs to be removed.\n\n## Typical flow\n\n### 1. Propose — find PII in a session\n\n```\nprivacy-propose session_url=<url>\n```\n\nReturns a list of CSS selectors the auto-configure pipeline identified as likely PII, with suggested rule names. Inspect the list — reject any false positives before proceeding.\n\n### 2. Create — persist the rules you want\n\n```\nprivacy-create selectors=[{\"selector\": \".email-field\"}, {\"selector\": \"#ssn\"}]\n```\n\nRules land in `PREVIEW_SESSIONS_ONLY` scope. They only apply to preview sessions until promoted.\n\n### 3. Verify — list and review\n\n```\nprivacy-list\nprivacy-list scope_filter=preview\n```\n\nReview what was created. Note the `rule_id` values — you'll need them for delete or promote.\n\n### 4. Promote or delete\n\nPromote to activate for all sessions:\n```\nprivacy-promote rule_ids=[\"<id1>\", \"<id2>\"]\n```\n\nDelete if the rule was wrong:\n```\nprivacy-delete rule_ids=[\"<id1>\"]\n```\n\n## Gotchas\n\n- Running `propose` without reviewing the output — it's a starting point, not ground truth. Inspect selectors for false positives before creating rules.\n- Creating rules and immediately promoting — always verify with a preview session first. The preview scope exists for exactly this purpose.\n- Trying to delete a promoted rule — `delete` only works on preview-scoped rules.\n- Using `unmask` as `block_type` in `create` — this is rejected. Unmask rules are system-managed.\n- Assuming `privacy-url-create` / `privacy-network-create` land in a preview scope like element rules — they don't. They apply to all sessions the moment they're created, so double-check the pattern/regex before calling.\n- Using `request_body=\"record\"` (or `response_body=\"record\"`) in `privacy-network-create` — this is rejected; only `elide` and `whitelist` are supported for automated creation.\n- Passing `guid` to `privacy-url-create` with only the field you want to change — update is a full replace, so omitted fields (name, condition, exclusions) are lost, not preserved. Fetch the current rule from `privacy-url-list` first and resend its full state.\n- Forgetting `overwrite=true` on `privacy-network-create` when you meant to change an existing rule — without it, a matching `url_regex` is silently skipped, not updated.\n\n## See Also\n\n- `subtext-shared` — MCP conventions\n- `subtext-session` — session replay tools (for obtaining a session URL to pass to `propose`)\n"
}