Add measurement release, CAPI, and event-surface readiness

.claude-plugin/marketplace.json

@@ -99,7 +99,7 @@
     {
       "name": "gads-gtm-plugin",
       "source": "./gads-gtm-plugin",
-      "description": "Google Ads & GTM automation suite — 6 skills for conversion tracking: create GAds conversions via API, wire into GTM via MCP, audit containers, debug tag firing, Meta/CAPI assessment"
+      "description": "Google Ads & GTM automation suite — 9 skills for authorized DOM event auditing, conversion tracking, cross-platform server-side conversion readiness, and GTM/sGTM release baselining"
     },
     {
       "name": "openclaw-tools",

README.md

@@ -618,13 +618,13 @@ Semantic code analysis MCP server for intelligent code understanding and refacto
 
 ### gads-gtm-plugin ⭐ NEW
 
-Google Ads & GTM automation suite — create conversion actions, wire into GTM, audit containers, and validate tracking infrastructure.
+Google Ads & GTM automation suite — inventory authorized website event surfaces, create conversion actions, wire into GTM, validate cross-platform server-side conversion processes, and baseline published measurement releases.
 
 ```
 /plugin install gads-gtm-plugin@organized-ai-marketplace
 ```
 
-**6 Skills:**
+**9 Skills:**
 
 | Skill | Description |
 | --- | --- |
@@ -634,6 +634,9 @@ Google Ads & GTM automation suite — create conversion actions, wire into GTM,
 | `gtm-debug-agent` | Browser-based GTM debugging — tag firing, dataLayer inspection, consent mode |
 | `gads-to-gtm-programmatic` | End-to-end: create Google Ads conversions via API → wire labels into GTM via MCP |
 | `gads-conversion-flow` | Lightweight: create Google Ads conversions and retrieve labels for GTM |
+| `measurement-release-versioning` | Capture published GTM/sGTM versions, event/pixel mappings, and aggregate outcomes for governed comparison |
+| `conversion-api-process` | Plan and validate consent-gated Google Ads, Meta, TikTok, and X server-side conversion delivery |
+| `event-surface-audit` | Convert an authorized, read-only Apify DOM inventory into a GTM/sGTM event-capture proposal |
 
 **Commands:**
 
@@ -642,6 +645,9 @@ Google Ads & GTM automation suite — create conversion actions, wire into GTM,
 | `/gtm-audit` | Full GTM container audit with health score |
 | `/gads-setup` | Create Google Ads conversion actions + wire into GTM |
 | `/tracking-check` | Validate entire tracking stack (GTM + GAds + Meta) |
+| `/measurement-release` | Capture a pre-change GTM/sGTM baseline manifest |
+| `/conversion-api-readiness` | Validate cross-platform server-side conversion readiness |
+| `/event-surface-audit` | Build a proposed event map from an Apify DOM inventory dataset |
 
 **Agents:**
 

gads-gtm-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gads-gtm-plugin",
-  "version": "1.0.0",
-  "description": "Google Ads & GTM automation suite — audit, build, debug, and optimize conversion tracking infrastructure programmatically via MCP servers.",
+  "version": "1.3.0",
+  "description": "Google Ads & GTM automation suite — audit event surfaces, build, debug, version releases, and govern cross-platform server-side conversion processes.",
   "author": {
     "name": "Blue Highlighted Text",
     "url": "https://github.com/organized-ai"
@@ -17,7 +17,14 @@
     "meta-ads",
     "data-audit",
     "stape",
-    "mcp"
+    "mcp",
+    "measurement-versioning",
+    "release-management",
+    "conversions-api",
+    "server-side-conversions",
+    "apify",
+    "event-audit",
+    "dom-inventory"
   ],
   "category": "data-infrastructure",
   "skills": [
@@ -26,6 +33,9 @@
     "skills/tidy-gtm",
     "skills/gtm-debug-agent",
     "skills/gads-to-gtm-programmatic",
-    "skills/gads-conversion-flow"
+    "skills/gads-conversion-flow",
+    "skills/measurement-release-versioning",
+    "skills/conversion-api-process",
+    "skills/event-surface-audit"
   ]
 }

gads-gtm-plugin/AGENT-SETUP.md

@@ -0,0 +1,39 @@
+# Use this measurement kit with another coding agent
+
+The marketplace package is native to Claude Code. The measurement artifacts themselves are portable: any agent that can read files and run a local command can use the same audit workflow.
+
+## Claude Code (native install)
+
+```text
+/plugin marketplace add Organized-AI/plugin-marketplace
+/plugin install gads-gtm-plugin@organized-ai-marketplace
+```
+
+Then ask: “Read `skills/event-surface-audit/SKILL.md` and use the included DOM Event Inventory Actor to create a proposed GTM event plan. Do not publish.”
+
+## Any other coding agent (portable install)
+
+1. Clone this repository or download the `gads-gtm-plugin` folder into the project the agent can read.
+2. Give the agent this one-time instruction:
+
+   ```text
+   Follow gads-gtm-plugin/skills/event-surface-audit/SKILL.md.
+   Use only authorized, read-only website inventories. Treat generated event maps as proposals;
+   do not publish GTM, send conversions, click controls, submit forms, or expose secrets.
+   ```
+
+3. Run the actor and deterministic mapper from [QUICKSTART.md](QUICKSTART.md). Give the exported dataset and generated `event-surface-map.json` to the agent.
+4. If the agent supports MCP, copy the applicable entries from [`.mcp.json`](.mcp.json) into that agent’s MCP settings. Add credentials through its secure configuration flow; never paste a token into source control or chat.
+
+The agent’s own MCP configuration syntax and installation screen differ by product, so this guide deliberately provides portable files and a portable prompt instead of claiming a one-click install where none exists.
+
+## Reproducible hand-off bundle
+
+Give a novice these four things:
+
+- `QUICKSTART.md` for the human procedure;
+- `actors/dom-event-inventory/` to deploy or run the read-only Apify Actor;
+- an exported dataset plus `scripts/build_event_surface_map.py` for repeatable event proposals;
+- `config/conversion-api-readiness.example.json` and `scripts/create_measurement_release.py` for the server-side and versioning gates.
+
+No item contains an advertising credential. Keep production destination IDs, platform tokens, and personal data out of the bundle.

gads-gtm-plugin/QUICKSTART.md

@@ -0,0 +1,102 @@
+# Quick Start: website events → GTM → sGTM/CAPI
+
+This guide is designed for a technical novice. It produces a **proposal**, then asks you to test it. Nothing in this plugin publishes a GTM container, clicks a website control, submits a form, or sends an ad-platform conversion by itself.
+
+## 1. Install the plugin
+
+In Claude Code, add this marketplace once, then install the plugin:
+
+```text
+/plugin marketplace add Organized-AI/plugin-marketplace
+/plugin install gads-gtm-plugin@organized-ai-marketplace
+```
+
+Restart Claude Code if it does not immediately show the commands. This repository is a Claude Code marketplace, so those are the one-command install instructions. Other coding agents can still use the same Actor, JSON contracts, scripts, and MCP configuration, but their plugin-install format is host-specific; point the agent at this plugin folder and ask it to follow `skills/event-surface-audit/SKILL.md`. Do not represent it as a native install for an agent that does not support Claude plugins.
+
+## 2. Decide what you are allowed to audit
+
+Use the DOM inventory only for a domain you own or have written authorization to assess. Start with 5–10 public pages. Do not use it for logged-in areas, session replay, form submission, credential collection, or consent bypass. Its output intentionally excludes input values and URL query strings.
+
+## 3. Create a DOM inventory with Apify
+
+The Actor uses a browser because many modern sites render controls with JavaScript. It **does not click controls or submit forms**; it reports visible links, buttons, forms, and fields plus conservative selector evidence.
+
+Prerequisites: Node.js 22+, an Apify account, and the Apify CLI.
+
+```bash
+npm install -g apify-cli
+apify login
+cd gads-gtm-plugin/actors/dom-event-inventory
+npm ci
+npm run build
+apify push
+```
+
+After the first push, run it from the Apify Console with the contents of `../../examples/dom-event-inventory.input.json`, replacing `https://example.com/` with your authorized website. Keep `sameDomainOnly` enabled for a first pass. Export the resulting default dataset as JSON to `dom-inventory.json`.
+
+Apify documents `apify login` followed by `apify push` as the CLI deployment path; its Playwright crawler is designed for JavaScript-rendered pages and can save results to the Actor dataset. [Apify deployment docs](https://docs.apify.com/actors/development/deployment) and [PlaywrightCrawler guide](https://docs.apify.com/sdk/js/docs/guides/playwright-crawler) cover those primitives.
+
+## 4. Turn the inventory into an event plan
+
+```bash
+cd ../..
+python3 scripts/build_event_surface_map.py \
+  --input dom-inventory.json \
+  --out event-surface-map.json
+```
+
+Or, in Claude Code:
+
+```text
+/event-surface-audit dom-inventory.json
+```
+
+Review every candidate. `cta_clicked` means “a clickable thing was found,” not “this is a conversion.” Retain only actions that matter to the business: lead form start/submit, qualified survey result, checkout completion, account creation, or a meaningful CTA.
+
+For each retained event, agree on a small metadata allowlist. Good examples: `page_type`, `form_id`, `step`, `content_id`, `experiment_id`. Do not include form text, email, phone, address, full URLs with query strings, access tokens, or ad-platform secrets.
+
+## 5. Capture client-side events safely
+
+Ask your developer to emit the event at the confirmed business action—not merely when a button is clicked:
+
+```javascript
+window.dataLayer = window.dataLayer || [];
+window.dataLayer.push({
+  event: 'quiz_result_viewed',
+  event_id: crypto.randomUUID(),
+  use_case: 'measurement_audit',
+  platform_selection: ['google_ads', 'meta']
+});
+```
+
+Use a stable `data-track` or `data-event` attribute only if application instrumentation is not available. In GTM, build triggers and variables in a **test workspace**, use Preview/Tag Assistant, and verify that consent blocks advertising events when it should.
+
+## 6. Add server-side destinations only after browser validation
+
+Send the approved event through sGTM/Stape only after the client-side data layer is verified. Keep the same `event_id` in matching browser/server Meta and TikTok events. For X, use the same `conversion_id` for an overlapping Pixel/CAPI event. Store credentials only in Stape or secret management, never in GTM variables, source files, exported manifests, or prompts.
+
+Copy the readiness template and validate it before enabling a destination:
+
+```bash
+cp config/conversion-api-readiness.example.json my-capi-readiness.json
+python3 scripts/check_conversion_api_readiness.py --config my-capi-readiness.json
+```
+
+Then send a test event and confirm it in each platform’s diagnostic view. Do not publish until the event, consent behavior, and deduplication are proven.
+
+## 7. Version and compare the measurement release
+
+Before publishing, capture the current web GTM and sGTM container version IDs:
+
+```text
+/measurement-release <release-id> <web-container> <web-version> <server-container> <server-version>
+```
+
+After the release, save aggregate results and diagnostic evidence under the same release. Compare equivalent windows and event definitions; a before/after change alone does not prove that a container edit caused a performance change.
+
+## What to ask your agent
+
+- “Use `event-surface-audit` on this Apify dataset. Return only a proposed event map and ask me to approve it.”
+- “Implement approved events in a GTM test workspace, then give me Preview evidence. Do not publish.”
+- “Run conversion-api readiness for Meta and TikTok; do not include credentials in files or chat.”
+- “Create a measurement release manifest for the currently published web GTM and sGTM versions.”

gads-gtm-plugin/README.md

@@ -2,7 +2,7 @@
 
 > Production-grade Google Ads & GTM automation suite for Claude Code. Audit, build, debug, and optimize conversion tracking infrastructure programmatically via MCP servers.
 
-## Skills (6)
+## Skills (9)
 
 | Skill | Purpose |
 |-------|---------|
@@ -12,6 +12,9 @@
 | **gtm-debug-agent** | Browser-based GTM debugging — tag firing verification, dataLayer inspection, consent mode validation |
 | **gads-to-gtm-programmatic** | End-to-end: create Google Ads conversion actions via API → wire labels into GTM tags/variables via MCP |
 | **gads-conversion-flow** | Lightweight: create Google Ads conversions and retrieve labels for manual GTM wiring |
+| **measurement-release-versioning** | Capture published GTM/sGTM versions, pixel mappings, and baseline outcomes for governed before/after comparison |
+| **conversion-api-process** | Configure and validate consent-gated server-side conversion processes for Google Ads, Meta, TikTok, and X |
+| **event-surface-audit** | Turn an authorized, read-only Apify DOM inventory into a consent-aware client-side and server-side event proposal |
 
 ## MCP Servers Required
 
@@ -40,6 +43,9 @@
 | `/gtm-audit` | Full GTM container audit with health score |
 | `/gads-setup` | Create Google Ads conversion actions + wire into GTM |
 | `/tracking-check` | Validate entire tracking stack (GTM + GAds + Meta) |
+| `/event-surface-audit` | Create a GTM-ready event map from a DOM inventory dataset |
+| `/measurement-release` | Capture a GTM/sGTM measurement release baseline |
+| `/conversion-api-readiness` | Validate cross-platform CAPI readiness without exposing credentials |
 
 ## Agents
 
@@ -60,6 +66,26 @@
 1. `tidy-gtm` → audit and clean
 2. `gtm-ai` → bulk tag/trigger/variable operations
 3. `gtm-debug-agent` → validate changes before publish
+4. `measurement-release-versioning` → capture the immutable baseline before and after a published release
+5. `conversion-api-process` → validate browser/server event mappings, consent, deduplication, and platform test evidence
+
+**Website event discovery (authorized sites only):**
+1. Follow [QUICKSTART.md](QUICKSTART.md) to deploy or run the included read-only Apify Actor
+2. `event-surface-audit` → convert the DOM inventory into candidate events and a GTM data-layer contract
+3. Configure and validate in a GTM preview workspace; do not auto-publish DOM-derived triggers
+4. `measurement-release-versioning` and `conversion-api-process` → baseline the change and validate server destinations
+
+## Measurement releases
+
+Use `/measurement-release` before a tracking deployment. It creates a privacy-safe manifest linking published web GTM and sGTM version IDs to event-contract and pixel/destination mappings, an evaluation window, and aggregate results. It complements the existing GTM deployment flow; it does not publish or modify a container.
+
+## Cross-platform conversion processes
+
+Use `/conversion-api-readiness` to validate the setup plan for Google Ads, Meta CAPI, TikTok Events API, and X CAPI before production event delivery. It checks the shared event contract, consent gate, browser/server deduplication identifiers, destination IDs, secret storage, test evidence, and diagnostics ownership. It never stores or prints credentials.
+
+## Novice quick start
+
+Start with [QUICKSTART.md](QUICKSTART.md). It explains marketplace installation, the authorized Apify DOM inventory, GTM preview validation, sGTM/CAPI routing, and release versioning. For non-Claude agents, use the portable hand-off in [AGENT-SETUP.md](AGENT-SETUP.md). The actor only inventories public page structure; it neither clicks controls nor submits forms.
 
 ## License
 

gads-gtm-plugin/actors/dom-event-inventory/.actor/Dockerfile

@@ -0,0 +1,16 @@
+FROM apify/actor-node-playwright-chrome:22 AS builder
+
+COPY package*.json ./
+RUN npm ci --include=dev --audit=false
+COPY tsconfig.json ./
+COPY src/ ./src/
+RUN npm run build
+
+FROM apify/actor-node-playwright-chrome:22
+
+COPY package*.json ./
+RUN npm ci --omit=dev --audit=false
+COPY --from=builder /home/myuser/dist ./dist
+COPY .actor/ ./.actor/
+
+CMD ["node", "dist/main.js"]

gads-gtm-plugin/actors/dom-event-inventory/.actor/actor.json

@@ -0,0 +1,9 @@
+{
+  "actorSpecification": 1,
+  "name": "dom-event-inventory",
+  "title": "DOM Event Inventory",
+  "description": "Read-only inventory of public interactive page elements for GTM measurement planning.",
+  "version": "1.0.0",
+  "input": "./input_schema.json",
+  "dockerfile": "./Dockerfile"
+}

gads-gtm-plugin/actors/dom-event-inventory/.actor/input_schema.json

@@ -0,0 +1,38 @@
+{
+  "title": "DOM Event Inventory input",
+  "type": "object",
+  "schemaVersion": 1,
+  "properties": {
+    "startUrls": {
+      "title": "Start URLs",
+      "type": "array",
+      "description": "Pages you are authorized to audit.",
+      "editor": "requestListSources",
+      "prefill": [{ "url": "https://example.com/" }]
+    },
+    "maxPages": {
+      "title": "Maximum pages",
+      "type": "integer",
+      "description": "Keep this small for a first audit.",
+      "default": 10,
+      "editor": "textfield"
+    },
+    "sameDomainOnly": {
+      "title": "Same domain only",
+      "type": "boolean",
+      "description": "Do not follow links outside the first start URL's domain.",
+      "default": true,
+      "editor": "select",
+      "enum": [true, false],
+      "enumTitles": ["Yes", "No"]
+    },
+    "maxElementsPerPage": {
+      "title": "Maximum elements per page",
+      "type": "integer",
+      "description": "Caps reported controls; no controls are clicked.",
+      "default": 250,
+      "editor": "textfield"
+    }
+  },
+  "required": ["startUrls"]
+}

gads-gtm-plugin/actors/dom-event-inventory/.actorignore

@@ -0,0 +1,6 @@
+.git/
+node_modules/
+dist/
+storage/
+apify_storage/
+*.md

gads-gtm-plugin/actors/dom-event-inventory/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+storage/
+apify_storage/
+.env