Add Deduplicate and Rate Limit action reference and example (#27)

Documents the two families of built-in coordination actions that give workflows shared, distributed state: Deduplicate (atomic once-only claim on a key) and Rate Limit (pace a workflow against a shared budget). Both are inline actions with no Foundry app, config_id, or credential.

Adds an authoring reference covering all six Deduplicate activities and all four Rate Limit activities, including the scope gotcha (the platform stores definition and cid, which the console labels "Workflow" and "CID"), the atomic claim and metadata handoff, and the save-time validation the builder runs. Adds a worked tutorial example that deduplicates third-party NG-SIEM detections into a single case, registered in the reference index and example catalog.

Action IDs and version constraints were confirmed against a live tenant with action_search.py, and the example passes validate.py at all tiers including server-side API validation. The actions are enabled in all commercial CIDs (US-1, US-2, EU-1 by default; other environments by request).

Author: mraible

CHANGELOG.md

@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 - US-3 cloud region to credential setup: a `[us-3]` profile example (`https://api.us-3.crowdstrike.com`) in the setup skill's multi-cloud block and in the README region notes, alongside a `[us-gov-1]` example that was also missing. The auth module already accepts any `base_url`, so this documents the host rather than changing behavior.
 - Throttling reference in the execution skill: explains that a workflow stuck "in progress" may be throttled (Fusion paces an action past a volume limit, auto-retrying up to 6 hours) rather than failed, how to recognize it on the execution detail view, and when sustained throttling signals a workflow-design issue.
+- Deduplicate and Rate Limit action reference plus a worked tutorial example. Covers all six Deduplicate activities and all four Rate Limit activities: the `definition`/`cid` scope values (which the console labels "Workflow" and "CID"), the atomic claim, metadata handoff, and the save-time validation the builder runs. The example deduplicates third-party NG-SIEM detections into a single case. Action IDs were confirmed against a live tenant; the example passes validation at all tiers.
 
 ## [1.0.1] - 2026-08-07
 

skills/authoring/SKILL.md

@@ -53,7 +53,7 @@ metadata:
 > only for actions the table does not cover.
 > 3. Run `trigger_search.py` to confirm the trigger type.
 > 4. Run `validate.py` on every YAML file before presenting it.
-> 5. **Re-run `validate.py` on the FINAL file; resolve every ERROR before finishing.** A file that still errors is not done. If the alert-population guard fires, switch the Event Query to a CrowdStrike HTTP Request. Never hand off a file that fails validation.
+> 5. **Re-run `validate.py` on the FINAL file; resolve every ERROR before finishing.** A file that still errors is not done. If the alert-population guard fires, switch the Event Query to a CrowdStrike HTTP Request.
 >
 > **MUST NOT:**
 > - Author a workflow for a Foundry-app-shaped request (see action 0) — redirect to foundry-skills.
@@ -253,7 +253,7 @@ force an immediate refresh so newly shipped action types are never hidden.
 | "The template has `PLACEHOLDER_RAN_006`, I'll copy it." | NEVER. Templates are structural guides. Substitute a real value before saving. |
 | "Validation can wait until deploy." | NO. Validate after authoring — `validate.py` catches PLACEHOLDERs, bad IDs, and schema errors locally. |
 | "This action has a `class`, version_constraint is optional." | WRONG. Class-based actions REQUIRE `version_constraint`. Missing it fails import. |
-| "I'll use `~1` everywhere for version_constraint." | NO. The value is `~<major>` of the action's `semantic_version` (`~0` when it declares none): `1.0.4` → `~1`, `0.0.100` (Charlotte AI, most Store plugins) → `~0`. Read it from `--details`. |
+| "I'll use `~1` everywhere for version_constraint." | NO. The value is `~<major>` of the action's `semantic_version` (`~0` when it declares none): `1.0.4` → `~1`, `0.0.100` → `~0`. Read it from `--details`. |
 | "I'll make up a `config_id` for this Okta action." | NEVER. It's CID-specific (exists only once configured in the console). Ask the user (AskUserQuestion) — even non-interactively. Sequential/all-zeros/repeated-char UUIDs are still fabricated and fail at runtime; can't get a real one? STOP. See `references/best-practices.md`. |
 | "I'll set `definition_id: VIRUSTOTAL_..._ID` on this HTTP action." | NEVER. An `Inline.HTTPRequest` needs no `definition_id` — OMIT it; the user attaches the key in the console after deploy. A placeholder is a broken ref `validate.py` flags. |
 | "The Send email field is called Recipients, so I'll use `recipients:`." | WRONG. The property KEY is `to:` (a list); `recipients:` is rejected. Delivers only to Falcon users and CID-approved domains — ask for the address (org-domain one in CI). |
@@ -282,6 +282,7 @@ the task actually calls for them:
 | Run a CQL/FQL event query in a step — inputs, outputs | `references/event-query-action.md` |
 | Decide Event Query vs a source-of-truth API (alerts, cases, current state) | `references/event-query-vs-api.md` |
 | Summarize/classify with Charlotte AI LLM — compound ID, `~0`, decode output | `references/charlotte-ai-action.md` |
+| Deduplicate or rate-limit a workflow — scopes, keys | `references/deduplicate-ratelimit.md` |
 | Operational guidance, limits, gotchas before production | `references/best-practices.md` |
 
 **Advanced (rarely needed):**

skills/authoring/examples/README.md

@@ -14,7 +14,7 @@ network containment, notifications, and more.
 | `notifications/` | 2 | Alert routing, Slack notifications, and human-approved endpoint containment. |
 | `ngsiem/` | 1 | Falcon Next-Gen SIEM duplicate-detection management. |
 | `response-actions/` | 6 | Palo Alto Networks NGFW integration for network-level response (DAG tags, EDLs). |
-| `tutorials/` | 8 | "Introduction to..." playbooks teaching specific Fusion concepts. |
+| `tutorials/` | 9 | "Introduction to..." playbooks teaching specific Fusion concepts. |
 
 ## Workflows
 
@@ -59,6 +59,7 @@ network containment, notifications, and more.
 - [Introduction to the Python script action: build a lookup file from an external feed](tutorials/intro-python-sslbl-lookup.yaml) — an `Inline.Python` action fetches and reshapes the abuse.ch SSL blocklist, and its `output_stdout` feeds a lookup file
 - [Introduction to Receive Email trigger: How to create a lookup file from an email attachment](tutorials/intro-receive-email-trigger.yaml)
 - [Introduction to variables: How to append to an array](tutorials/intro-variables-append-array.yaml)
+- [Introduction to deduplication: How to deduplicate third-party detections](tutorials/intro-deduplicate-third-party-detections.yaml) — the **Deduplicate** action family suppresses duplicate NG-SIEM third-party (Palo Alto) detections: a sha1 key over a 24h window creates one case and comments duplicates onto it. See `references/deduplicate-ratelimit.md`. **Pre-GA** — action IDs are from a console export, not yet live-verified in our tenant
 - [CrowdStrike HTTP Request: query the Falcon Alerts API and email the result](tutorials/crowdstrike-http-request-falcon-api.yaml) — the canonical **CrowdStrike HTTP Request** shape (Falcon platform API, distinct from a Cloud HTTP Request): absolute region host, query params in `request_query` (not the URL), required OAuth credential (`UseExisting` + `config_id`). Built and executed live end-to-end.
 
 ## How to use these examples

skills/authoring/examples/tutorials/intro-deduplicate-third-party-detections.yaml

@@ -0,0 +1,103 @@
+# Source: CrowdStrike-authored tutorial workflow "Introduction to
+# deduplication: How to Deduplicate Third Party Detections", exported from the
+# Falcon console. Demonstrates the Deduplicate action family suppressing
+# duplicate third-party (Palo Alto) NG-SIEM detections into a single case.
+#
+# Availability: The Deduplicate and Rate Limit actions are enabled in all
+# commercial CIDs, and are available in US-1, US-2, and EU-1 by default (other
+# environments by request). The action IDs and version_constraints below were
+# confirmed against a live tenant with action_search.py, and this file passes
+# validate.py at all tiers, including server-side API validation.
+#
+# Pattern: NG-SIEM third-party detection (Palo Alto) -> Deduplicate on a sha1 key
+# built from detection type + source/dest IPs, 24h window -> if new, create a
+# case and record its ID as the entry's metadata -> if duplicate, wait for that
+# metadata and comment on the original case. See
+# references/deduplicate-ratelimit.md.
+# This is an exported workflow. Editing this file is not recommended.
+
+name: 'Introduction to deduplication: How to Deduplicate Third Party Detections'
+description: Learn how to leverage the deduplication action to deduplicate third party detections from Palo Alto Networks
+disconnected_nodes:
+    - '{"id":"notes_b5eee5d5-1646-4562-9e25-f933d06a9ed0","position":{"x":304.24687139282736,"y":526.301954879066},"node_type":"notes","comment":"Dedups for a period of one day"}'
+trigger:
+    next:
+        - data39trigger_detection_thirdparty_sourcevendors39_existsone__v_v__34paloalto34
+    event: Investigatable/THIRDPARTY
+    name: Detection > NG-SIEM Third Party Detection
+    type: Signal
+    version_constraint: ~1
+actions:
+    AddCommentToCase:
+        id: a16f4fdd1b244b0bfeecd47e25dbe0e0
+        default_name: Add Comment to Case
+        name: Add Comment to Case
+        properties:
+            case_id: ${data['WaitForDeduplicateEntryMetadata.metadata']}
+            comment: 'Detection ID: ${data[''Trigger.Detection.DetectionID'']} is a duplicate.'
+        version_constraint: ~1
+    CreateANewCase:
+        id: 4918bf9d85ecc06388eca16543bdbbdc
+        default_name: Create a new Case
+        name: Create a new Case
+        next:
+            - SetDeduplicateEntryMetadata
+        properties:
+            description: |-
+                Name: ${data['Trigger.Detection.Name']}
+                Description: ${data['Trigger.Detection.Description']}
+            detections:
+                - ${Trigger.Detection.DetectionID}
+            name: Detection ${data['Trigger.Detection.Name']}
+            severity_level: 3
+            status: new
+        version_constraint: ~1
+    Deduplicate:
+        id: f6f68f316170550b2777aec3dc3c85e1
+        default_name: Deduplicate
+        name: Deduplicate
+        next:
+            - duplicate_is_equal_to_false
+        properties:
+            key: |-
+                ${cs.hash.sha1(data['Trigger.Detection.ThirdParty.DetectionType'] +
+                data['Trigger.Detection.ThirdParty.SourceIPs'].join(",") +
+                data['Trigger.Detection.ThirdParty.DestinationIPs'].join(","))}
+            period: 86400
+            scope: definition
+        version_constraint: ~2
+    SetDeduplicateEntryMetadata:
+        id: 7cd6f7bde9eef6a98d851d8270e4f1f4
+        default_name: Set Deduplicate Entry Metadata
+        name: Set Deduplicate Entry Metadata
+        properties:
+            key: ${data['Deduplicate.key']}
+            metadata: ${data['CreateANewCase.id']}
+            scope: definition
+        version_constraint: ~1
+    WaitForDeduplicateEntryMetadata:
+        id: 7bddab2fa0d5c5c90fdb49e0f3eef380
+        default_name: Wait for Deduplicate Entry Metadata
+        name: Wait for Deduplicate Entry Metadata
+        next:
+            - AddCommentToCase
+        properties:
+            key: ${data['Deduplicate.key']}
+            scope: definition
+        version_constraint: ~1
+conditions:
+    data39trigger_detection_thirdparty_sourcevendors39_existsone__v_v__34paloalto34:
+        next:
+            - Deduplicate
+        cel_expression: data['Trigger.Detection.ThirdParty.SourceVendors'].existsOne(_, v, v == "Paloalto")
+        display:
+            - data['Trigger.Detection.ThirdParty.SourceVendors'].existsOne(_, v, v == "Paloalto")
+        name: If Vendor is Palo Alto
+    duplicate_is_equal_to_false:
+        next:
+            - CreateANewCase
+        expression: Deduplicate.duplicate:false
+        display:
+            - Duplicate is equal to False
+        else:
+            - WaitForDeduplicateEntryMetadata