From aa06660a979db7513b39085369d11768e24989c7 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Mon, 31 Aug 2026 22:29:27 +0100
Subject: [PATCH 1/6] feat(analytics): route GA4 through GTM and instrument
 engagement events

Swap the bare ga4 integration in docs.json for GTM (tagId placeholder
until the container is created), fire dataLayer events from
AddNetworkButton for the add-network conversion, and document the
measurement setup in ANALYTICS.md: GTM/GA4 runbooks for humans and a
Cloudflare AI Crawl Control runbook for bot/agent traffic, which no
client-side tag can see.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 AGENTS.md                     |  1 +
 ANALYTICS.md                  | 80 +++++++++++++++++++++++++++++++++++
 docs.json                     |  4 +-
 snippets/AddNetworkButton.jsx | 22 ++++++++--
 4 files changed, 101 insertions(+), 6 deletions(-)
 create mode 100644 ANALYTICS.md

diff --git a/AGENTS.md b/AGENTS.md
index a56badb36..0eff48bbc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,7 @@ Structural work in progress is tracked in the restructure epic, [#2266](https://
 - `snippets/` holds reusable JSX/MDX (`/snippets/ColoredText.jsx`, `/snippets/YouTube.jsx`, `/snippets/AddNetworkButton.jsx`). Import with an absolute path after the frontmatter: `import {YouTube} from '/snippets/YouTube.jsx'`.
 - Static assets: `img/`, `images/`, `assets/`, `logo/`.
 - **Any `.js` file under the content root runs on every published page.** Mintlify injects them automatically — there is no allowlist and no way to scope one to a single page — and the same applies to `.css`. Treat a `.js` file here as production code shipped to every reader, not as content: it has full same-origin DOM access on pages that print contract addresses and RPC endpoints. Mintlify does not support a raw `<script src>` in MDX, so third-party scripts are injected programmatically from such a file (`assistant.js` is the example). Note `submodules/developer-tooling` sits under this root too.
+- Site analytics (GA4 via Google Tag Manager for humans, Cloudflare AI Crawl Control for bots/agents) are documented in [ANALYTICS.md](./ANALYTICS.md).
 
 ### Commands
 
diff --git a/ANALYTICS.md b/ANALYTICS.md
new file mode 100644
index 000000000..d5c6cb501
--- /dev/null
+++ b/ANALYTICS.md
@@ -0,0 +1,80 @@
+# ANALYTICS.md — how docs.celo.org is measured
+
+Internal doc for maintainers. Not listed in `docs.json` `navigation`, so it is not a public docs page.
+
+## Architecture
+
+Two hard constraints shape everything here:
+
+1. **The site is Mintlify-hosted.** There is no server, build step, or HTML template we control. Client-side tracking goes through the `integrations` block in `docs.json` and `window.dataLayer` pushes from `snippets/*.jsx`.
+2. **AI crawlers and fetchers never execute JavaScript.** GPTBot, ClaudeBot, PerplexityBot, ChatGPT-User, Claude-User, Claude Code, Cursor and the rest read `llms.txt`, `llms-full.txt` and the `.md` variant of every page directly. No client-side tool (GA4, PostHog, anything) can ever count them. They are only visible at the serving layer.
+
+So measurement is split in two:
+
+| Audience | Tool | Where |
+|---|---|---|
+| Humans (browsers) | GA4 `G-0CXEKQ81V2`, tags managed in Google Tag Manager | `docs.json` → `integrations.gtm` |
+| Bots and AI agents | Cloudflare AI Crawl Control (free tier), proxied in front of the domain | Cloudflare zone for `celo.org` |
+
+## Ownership
+
+| Asset | ID | Owner |
+|---|---|---|
+| GA4 property | `G-0CXEKQ81V2` | _fill in_ |
+| GTM container | `GTM-XXXXXXX` (placeholder — replace in `docs.json` when created) | _fill in_ |
+| Cloudflare zone / DNS for `docs.celo.org` | — | _fill in_ |
+| Mintlify org (Free/Starter plan) | — | _fill in_ |
+
+## What is instrumented in this repo
+
+- `docs.json` → `integrations.gtm.tagId` loads the GTM container on every page. GA4 itself is configured **inside** GTM (Google Tag), not in `docs.json` — having both would double-count page views.
+- `snippets/AddNetworkButton.jsx` pushes `dataLayer` events: `add_network_click` on click, and `add_network_result` with `result` = `success` | `rejected` | `error` | `no_wallet` and `network` = chain name. This is the highest-intent action on the site.
+- A handful of outbound partner links carry manual UTM parameters (`tooling/libraries-sdks/reown/index.mdx`, `tooling/indexers/goldrush.mdx`). The GTM outbound-click tag below covers outbound attribution generally, so new UTMs are not required.
+
+## Runbook 1: Google Tag Manager container
+
+Create a **Web** container for `docs.celo.org` at https://tagmanager.google.com, then replace `GTM-XXXXXXX` in `docs.json` with the real ID. Configure:
+
+- [ ] **Google Tag** with tag ID `G-0CXEKQ81V2`, firing on All Pages and on History Changes (Mintlify navigates client-side; without the history trigger only the first page view is counted).
+- [ ] **Scroll depth**: built-in Scroll Depth trigger at 25 / 50 / 75 / 90 % → GA4 event `scroll_depth` with parameter `percent_scrolled` (`{{Scroll Depth Threshold}}`). GA4's own enhanced measurement fires only at 90 %, which hides most drop-off.
+- [ ] **Outbound clicks**: Just Links trigger with condition Click URL does not contain `docs.celo.org` → GA4 event `outbound_click` with `link_domain` (`{{Click URL Hostname}}` — create a URL variable with component "Host Name") and `link_url` (`{{Click URL}}`).
+- [ ] **Code copy**: Click trigger on Mintlify's code-block copy button → GA4 event `copy_code` with `page_path`. The selector targets Mintlify's rendered UI and can change without notice — verify with GTM Preview after Mintlify updates.
+- [ ] **AI-menu clicks**: Click trigger on the page-level contextual menu (Copy page / ChatGPT / Claude / Cursor / VS Code / MCP — the `contextual.options` in `docs.json`) → GA4 event `ai_menu_click` with `ai_target` set from the clicked item's text. Same selector caveat as above.
+- [ ] **AddNetworkButton events**: Custom Event triggers for `add_network_click` and `add_network_result` → GA4 event tags forwarding `network` and `result` as parameters (Data Layer variables).
+- [ ] **Automation heuristic**: Custom HTML tag (fires before the Google Tag, e.g. on Consent/Initialization) that pushes `{ is_automated: "true" }` to the dataLayer when `navigator.webdriver === true` or the user agent contains `HeadlessChrome`; attach `is_automated` as a parameter on the Google Tag. This is a weak signal, not a count — agentic browsers such as Comet and Atlas use stock Chrome user agents and are indistinguishable client-side.
+- [ ] Verify everything in GTM **Preview mode** against the live site, then **Publish**.
+
+## Runbook 2: GA4 property configuration
+
+In the GA4 property for `G-0CXEKQ81V2` (Admin):
+
+- [ ] **Custom channel group "AI Assistants"**: condition Session source matches regex
+  `chatgpt\.com|chat\.openai\.com|claude\.ai|perplexity\.ai|gemini\.google\.com|copilot\.microsoft\.com|grok\.com|x\.ai|deepseek\.com|you\.com|phind\.com|meta\.ai`
+  GA4's built-in "AI Assistant" channel recognizes only ChatGPT, Gemini, DeepSeek, Copilot and Grok — not Claude or Perplexity. Known limit: a large share of AI-referred sessions arrive with no referrer and land in Direct; this channel measures the floor, not the total.
+- [ ] **Custom dimensions** (event-scoped): `percent_scrolled`, `link_domain`, `ai_target`, `network`, `result`, `is_automated`.
+- [ ] **Explorations**: (a) free-form exploration with Page path + Exits for exit pages (GA4 has no standard exit report); (b) reverse Path exploration for drop-off journeys.
+
+Already answered by standard reports, no setup needed:
+
+- *"What domain did people come from?"* → Reports → Acquisition → Traffic acquisition (Session source / medium; add Session source as secondary dimension).
+- *"How much time do they spend, on what pages?"* → Reports → Engagement → Pages and screens (Average engagement time per page).
+- *"Where do people land?"* → Reports → Engagement → Landing pages.
+
+## Runbook 3: Cloudflare in front of docs.celo.org (bot visibility)
+
+This is the only layer that can see non-JS bot traffic. Mintlify supports Cloudflare as DNS provider with the proxy enabled:
+
+- [ ] Proxied (orange-cloud) CNAME for `docs.celo.org` pointing at the Mintlify target (per the Mintlify dashboard's custom-domain settings).
+- [ ] SSL/TLS mode **Full (strict)**.
+- [ ] **Disable "Always Use HTTPS"** for the zone (Mintlify requirement) and add no rules touching `/.well-known/acme-challenge`.
+- [ ] Enable **AI Crawl Control** (free plan): shows per-crawler activity (GPTBot, ClaudeBot, PerplexityBot, ChatGPT-User, Claude-User, Bytespider, CCBot, Amazonbot, …), the pages each crawler hits, crawl frequency and robots.txt compliance.
+- [ ] **Allow all AI crawlers.** These docs want to be read by agents; the tool is for measurement, not blocking. Check that no default block rules are active — Cloudflare default-blocks some AI crawler categories on new zones.
+- [ ] Sanity check after cutover: `curl -I https://docs.celo.org/llms.txt` returns 200 with a valid certificate; a normal page and its `.md` variant load.
+
+Cloudflare Analytics (total requests) vs GA4 (sessions) also gives a rough overall bot share as the delta between the two.
+
+## Known blind spots
+
+- **Referrer-less AI traffic**: many clicks out of ChatGPT/Claude/Perplexity carry no referrer and appear as Direct in GA4.
+- **JS-capable agentic browsers** (Comet, Atlas, computer-use agents) execute the GA4 tag and count as humans; `is_automated` catches only naive automation.
+- **MCP server queries** (`https://docs.celo.org/mcp`) are served by Mintlify and visible in neither GA4 nor Cloudflare page analytics. Mintlify's own analytics dashboard (human-vs-agent split, assistant/search analytics) requires a paid Mintlify plan — the current plan is Free/Starter; upgrading is the future option if MCP/assistant visibility becomes important.
diff --git a/docs.json b/docs.json
index b46e18eca..91ca5cc64 100644
--- a/docs.json
+++ b/docs.json
@@ -26,8 +26,8 @@
     }
   },
   "integrations": {
-    "ga4": {
-      "measurementId": "G-0CXEKQ81V2"
+    "gtm": {
+      "tagId": "GTM-XXXXXXX"
     }
   },
   "background": {
diff --git a/snippets/AddNetworkButton.jsx b/snippets/AddNetworkButton.jsx
index 653c6eb71..c5431c633 100644
--- a/snippets/AddNetworkButton.jsx
+++ b/snippets/AddNetworkButton.jsx
@@ -30,8 +30,19 @@ export const AddNetworkButton = ({ network = "mainnet" }) => {
   const [status, setStatus] = useState(null); // { kind: "success" | "error" | "info", text }
   const [pending, setPending] = useState(false);
 
+  // GTM picks these up and forwards them to GA4 (see /ANALYTICS.md).
+  // dataLayer is absent when GTM is blocked or not yet configured.
+  const track = (event, result) => {
+    window.dataLayer?.push({
+      event,
+      network: cfg.params.chainName,
+      ...(result ? { result } : {}),
+    });
+  };
+
   const handleClick = async () => {
     setStatus(null);
+    track("add_network_click");
 
     // Resolve the injected provider. With several wallets installed,
     // window.ethereum can be a non-MetaMask provider that auto-rejects
@@ -44,6 +55,7 @@ export const AddNetworkButton = ({ network = "mainnet" }) => {
         : eth;
 
     if (!provider || !provider.request) {
+      track("add_network_result", "no_wallet");
       setStatus({
         kind: "info",
         text: "No browser wallet detected. Install MetaMask, then try again.",
@@ -57,16 +69,18 @@ export const AddNetworkButton = ({ network = "mainnet" }) => {
         method: "wallet_addEthereumChain",
         params: [cfg.params],
       });
+      track("add_network_result", "success");
       setStatus({ kind: "success", text: `${cfg.params.chainName} added to your wallet.` });
     } catch (err) {
       // Log the raw error so the exact code/message is visible in devtools.
       console.error("wallet_addEthereumChain failed", err);
       // 4001 is the EIP-1193 "user rejected request" code; anything else is a
       // real failure, so surface the wallet's own message rather than masking it.
-      const text =
-        err && err.code === 4001
-          ? "Request cancelled in your wallet."
-          : `Couldn't add the network${err && err.message ? `: ${err.message}` : "."}`;
+      const rejected = err && err.code === 4001;
+      track("add_network_result", rejected ? "rejected" : "error");
+      const text = rejected
+        ? "Request cancelled in your wallet."
+        : `Couldn't add the network${err && err.message ? `: ${err.message}` : "."}`;
       setStatus({ kind: "error", text });
     } finally {
       setPending(false);

From 34e8b136be5dc7d2c5834536930b3dd7c1183627 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Mon, 31 Aug 2026 22:39:26 +0100
Subject: [PATCH 2/6] feat(analytics): set live GTM container ID

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 ANALYTICS.md | 2 +-
 docs.json    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/ANALYTICS.md b/ANALYTICS.md
index d5c6cb501..6fb9d1dcf 100644
--- a/ANALYTICS.md
+++ b/ANALYTICS.md
@@ -21,7 +21,7 @@ So measurement is split in two:
 | Asset | ID | Owner |
 |---|---|---|
 | GA4 property | `G-0CXEKQ81V2` | _fill in_ |
-| GTM container | `GTM-XXXXXXX` (placeholder — replace in `docs.json` when created) | _fill in_ |
+| GTM container | `GTM-NP9GP2BT` | _fill in_ |
 | Cloudflare zone / DNS for `docs.celo.org` | — | _fill in_ |
 | Mintlify org (Free/Starter plan) | — | _fill in_ |
 
diff --git a/docs.json b/docs.json
index 91ca5cc64..e2a274bb4 100644
--- a/docs.json
+++ b/docs.json
@@ -27,7 +27,7 @@
   },
   "integrations": {
     "gtm": {
-      "tagId": "GTM-XXXXXXX"
+      "tagId": "GTM-NP9GP2BT"
     }
   },
   "background": {

From 34508b031bcfa8f0b7f21698546c8f3ffccc72ed Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Wed, 2 Sep 2026 13:43:53 +0100
Subject: [PATCH 3/6] ci: exclude ANALYTICS.md from the orphan-page check

ANALYTICS.md is internal maintainer documentation, deliberately not in
docs.json navigation. The orphan check began enforcing when #2293 removed
its continue-on-error, so it now fails on the same category of file it
already excludes for README.md, AGENTS.md and CLAUDE.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 scripts/check-orphans.sh | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/check-orphans.sh b/scripts/check-orphans.sh
index 508c8da4a..821a64e31 100755
--- a/scripts/check-orphans.sh
+++ b/scripts/check-orphans.sh
@@ -35,6 +35,7 @@ find . \( -name '*.mdx' -o -name '*.md' \) \
   -not -path './scripts/*' \
   -not -path './README.md' \
   -not -path './AGENTS.md' \
+  -not -path './ANALYTICS.md' \
   -not -path './CLAUDE.md' \
   | sed 's|^\./||; s|\.mdx$||; s|\.md$||' | sort -u > "$page_files"
 

From e7fe61aff2714974da9d0fe26dd0aeb75d95f590 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Wed, 2 Sep 2026 16:25:51 +0100
Subject: [PATCH 4/6] docs(analytics): fill the ownership table and mark the
 completed runbook steps

Owners are teams rather than individuals: this repository is public, and
.github/CODEOWNERS already assigns /docs.json to the same team.

Also corrects three steps the doc described as pending that are done:
the GTM container exists and docs.json carries its ID, the Google tag now
resolves G-0CXEKQ81V2 with a history-change trigger, and docs.celo.org is
already proxied through Cloudflare. Records the tag-ID failure mode, since
it produces no error anywhere, and notes that cf-cache-status: HIT widens
the Cloudflare-vs-GA4 delta for reasons unrelated to bots.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ANALYTICS.md | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/ANALYTICS.md b/ANALYTICS.md
index 6fb9d1dcf..cfee5e479 100644
--- a/ANALYTICS.md
+++ b/ANALYTICS.md
@@ -18,12 +18,18 @@ So measurement is split in two:
 
 ## Ownership
 
+Owners are teams, not individuals — this repository is public, and `.github/CODEOWNERS`
+already assigns `/docs.json` to the same team. Request access through the team.
+
 | Asset | ID | Owner |
 |---|---|---|
-| GA4 property | `G-0CXEKQ81V2` | _fill in_ |
-| GTM container | `GTM-NP9GP2BT` | _fill in_ |
-| Cloudflare zone / DNS for `docs.celo.org` | — | _fill in_ |
-| Mintlify org (Free/Starter plan) | — | _fill in_ |
+| GA4 property | `G-0CXEKQ81V2` | `@celo-org/devrel` |
+| GTM container | `GTM-NP9GP2BT` | `@celo-org/devrel` |
+| Cloudflare zone / DNS for `docs.celo.org` | `celo.org` zone, `docs.celo.org` proxied | `@celo-org/devrel` |
+| Mintlify org (Free/Starter plan) | — | `@celo-org/devrel` |
+
+The permission that matters when a tag needs fixing is **Publish** on the GTM container;
+Edit rights cannot ship a change.
 
 ## What is instrumented in this repo
 
@@ -33,9 +39,16 @@ So measurement is split in two:
 
 ## Runbook 1: Google Tag Manager container
 
-Create a **Web** container for `docs.celo.org` at https://tagmanager.google.com, then replace `GTM-XXXXXXX` in `docs.json` with the real ID. Configure:
+The container exists (`GTM-NP9GP2BT`) and `docs.json` carries its ID. Remaining tags to configure at https://tagmanager.google.com:
+
+- [x] **Google Tag** with tag ID `G-0CXEKQ81V2`, firing on All Pages and on History Changes (Mintlify navigates client-side; without the history trigger only the first page view is counted). Verify against the published container rather than the GTM UI:
+
+  ```bash
+  curl -s "https://www.googletagmanager.com/gtag/js?id=GTM-NP9GP2BT" | grep -c "G-0CXEKQ81V2"   # must be >= 1
+  curl -s "https://www.googletagmanager.com/gtm.js?id=GTM-NP9GP2BT"                             # "vtp_tagId":"G-0CXEKQ81V2"
+  ```
 
-- [ ] **Google Tag** with tag ID `G-0CXEKQ81V2`, firing on All Pages and on History Changes (Mintlify navigates client-side; without the history trigger only the first page view is counted).
+  This tag briefly carried the **container's own ID** in the Tag ID field instead of the measurement ID. The container loaded, a tag fired, nothing errored, and GA4 received nothing — so check the payload, not the UI.
 - [ ] **Scroll depth**: built-in Scroll Depth trigger at 25 / 50 / 75 / 90 % → GA4 event `scroll_depth` with parameter `percent_scrolled` (`{{Scroll Depth Threshold}}`). GA4's own enhanced measurement fires only at 90 %, which hides most drop-off.
 - [ ] **Outbound clicks**: Just Links trigger with condition Click URL does not contain `docs.celo.org` → GA4 event `outbound_click` with `link_domain` (`{{Click URL Hostname}}` — create a URL variable with component "Host Name") and `link_url` (`{{Click URL}}`).
 - [ ] **Code copy**: Click trigger on Mintlify's code-block copy button → GA4 event `copy_code` with `page_path`. The selector targets Mintlify's rendered UI and can change without notice — verify with GTM Preview after Mintlify updates.
@@ -62,16 +75,16 @@ Already answered by standard reports, no setup needed:
 
 ## Runbook 3: Cloudflare in front of docs.celo.org (bot visibility)
 
-This is the only layer that can see non-JS bot traffic. Mintlify supports Cloudflare as DNS provider with the proxy enabled:
+This is the only layer that can see non-JS bot traffic. The proxy is already in place, so only the AI Crawl Control steps remain:
 
-- [ ] Proxied (orange-cloud) CNAME for `docs.celo.org` pointing at the Mintlify target (per the Mintlify dashboard's custom-domain settings).
+- [x] Proxied (orange-cloud) CNAME for `docs.celo.org` pointing at the Mintlify target. Confirmed: `celo.org` resolves to Cloudflare nameservers, `docs.celo.org` is a CNAME to `cname.vercel-dns.com`, and responses carry `cf-ray` and `cf-cache-status`, which only appear when traffic passes through the proxy.
 - [ ] SSL/TLS mode **Full (strict)**.
 - [ ] **Disable "Always Use HTTPS"** for the zone (Mintlify requirement) and add no rules touching `/.well-known/acme-challenge`.
 - [ ] Enable **AI Crawl Control** (free plan): shows per-crawler activity (GPTBot, ClaudeBot, PerplexityBot, ChatGPT-User, Claude-User, Bytespider, CCBot, Amazonbot, …), the pages each crawler hits, crawl frequency and robots.txt compliance.
 - [ ] **Allow all AI crawlers.** These docs want to be read by agents; the tool is for measurement, not blocking. Check that no default block rules are active — Cloudflare default-blocks some AI crawler categories on new zones.
 - [ ] Sanity check after cutover: `curl -I https://docs.celo.org/llms.txt` returns 200 with a valid certificate; a normal page and its `.md` variant load.
 
-Cloudflare Analytics (total requests) vs GA4 (sessions) also gives a rough overall bot share as the delta between the two.
+Cloudflare Analytics (total requests) vs GA4 (sessions) also gives a rough overall bot share as the delta between the two. Treat it as rough: `docs.celo.org` returns `cf-cache-status: HIT`, so Cloudflare serves many requests from cache that never reach the origin, widening the delta for reasons unrelated to bots.
 
 ## Known blind spots
 

From b440f5be2b8dabd57e4ca7170d0cc8137fb62876 Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Wed, 2 Sep 2026 16:38:03 +0100
Subject: [PATCH 5/6] docs(analytics): correct the MCP blind spot and source
 the plan claim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MCP requests are not invisible to Cloudflare — they traverse the proxy and
return cf-ray, so volume is measurable by path today. The real blind spot is
query content, which no layer here can show.

Also sources the Starter-plan claim to #2250 rather than asserting it, and
records that Pro was evaluated and declined there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ANALYTICS.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/ANALYTICS.md b/ANALYTICS.md
index cfee5e479..a6d73729f 100644
--- a/ANALYTICS.md
+++ b/ANALYTICS.md
@@ -26,7 +26,7 @@ already assigns `/docs.json` to the same team. Request access through the team.
 | GA4 property | `G-0CXEKQ81V2` | `@celo-org/devrel` |
 | GTM container | `GTM-NP9GP2BT` | `@celo-org/devrel` |
 | Cloudflare zone / DNS for `docs.celo.org` | `celo.org` zone, `docs.celo.org` proxied | `@celo-org/devrel` |
-| Mintlify org (Free/Starter plan) | — | `@celo-org/devrel` |
+| Mintlify org | Starter plan (established in #2250) | `@celo-org/devrel` |
 
 The permission that matters when a tag needs fixing is **Publish** on the GTM container;
 Edit rights cannot ship a change.
@@ -90,4 +90,6 @@ Cloudflare Analytics (total requests) vs GA4 (sessions) also gives a rough overa
 
 - **Referrer-less AI traffic**: many clicks out of ChatGPT/Claude/Perplexity carry no referrer and appear as Direct in GA4.
 - **JS-capable agentic browsers** (Comet, Atlas, computer-use agents) execute the GA4 tag and count as humans; `is_automated` catches only naive automation.
-- **MCP server queries** (`https://docs.celo.org/mcp`) are served by Mintlify and visible in neither GA4 nor Cloudflare page analytics. Mintlify's own analytics dashboard (human-vs-agent split, assistant/search analytics) requires a paid Mintlify plan — the current plan is Free/Starter; upgrading is the future option if MCP/assistant visibility becomes important.
+- **MCP query content** — not MCP volume. Requests to `https://docs.celo.org/mcp` *do* traverse Cloudflare (they return `cf-ray`, `cf-cache-status: DYNAMIC`), so request volume is visible in Cloudflare's HTTP analytics filtered by path. They are invisible to GA4, which needs JavaScript. What no layer here can show is **what was asked**: the question text, which tool was called, whether the answer cited anything.
+
+  Mintlify's own dashboard would cover part of that, but it needs the Pro plan ($450/mo), which #2250 evaluated and declined — the site was previously on Pro and deliberately moved to Starter. The intended source of query-level signal is instead the in-page assistant (#2286), which can log its own questions. That telemetry does not exist yet, so the docs-gap loop the assistant was chosen for is not closed.

From 9a476f73143d032a5838815ced1855682dd106cb Mon Sep 17 00:00:00 2001
From: GigaHierz <lenahierzi@hotmail.de>
Date: Wed, 2 Sep 2026 18:25:50 +0100
Subject: [PATCH 6/6] docs(analytics): document the assistant instrumentation
 that already exists

The assistant is instrumented on both sides, in celo-org/docs-ai-assistant:
widget.js emits seven GA4 events through the page's existing window.gtag,
and the chat route pushes {question, citedUrls, answered, ...} onto the
Upstash Redis list docs-assistant:questions, trimmed to the last 10,000.
This file previously said that telemetry did not exist.

Records the two real gaps: the assistant's event parameters are not in the
custom-dimension list, so they arrive but cannot be reported on; and
track() is a no-op unless window.gtag is defined, which needs re-checking
after the GA4-to-GTM swap.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ANALYTICS.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/ANALYTICS.md b/ANALYTICS.md
index a6d73729f..c7c93c951 100644
--- a/ANALYTICS.md
+++ b/ANALYTICS.md
@@ -35,6 +35,9 @@ Edit rights cannot ship a change.
 
 - `docs.json` → `integrations.gtm.tagId` loads the GTM container on every page. GA4 itself is configured **inside** GTM (Google Tag), not in `docs.json` — having both would double-count page views.
 - `snippets/AddNetworkButton.jsx` pushes `dataLayer` events: `add_network_click` on click, and `add_network_result` with `result` = `success` | `rejected` | `error` | `no_wallet` and `network` = chain name. This is the highest-intent action on the site.
+- The docs assistant is instrumented on both sides, in `celo-org/docs-ai-assistant` rather than in this repo:
+  - **Client (GA4).** `widget.js` reuses the page's existing `window.gtag` rather than loading a second tracker, and emits `assistant_opened`, `assistant_question` (`answered`, `escalated`, `truncated`), `assistant_escalate`, `assistant_new_chat`, `assistant_copy`, `assistant_citation_click` (`href`) and `assistant_error` (`from_api`, `status`). Question text is deliberately never sent to GA4.
+  - **Server (Redis).** `app/api/chat/route.ts` calls `logQuestion()`, which pushes `{question, model, citedUrls, answered, timestamp, refused}` onto the Upstash Redis list `docs-assistant:questions`, trimmed to the most recent 10,000. Without Redis configured it falls back to `console.log`, which on Vercel is short-retention only. **This list is the docs-gap signal** — the uncited questions in it are the pages that need writing.
 - A handful of outbound partner links carry manual UTM parameters (`tooling/libraries-sdks/reown/index.mdx`, `tooling/indexers/goldrush.mdx`). The GTM outbound-click tag below covers outbound attribution generally, so new UTMs are not required.
 
 ## Runbook 1: Google Tag Manager container
@@ -64,7 +67,8 @@ In the GA4 property for `G-0CXEKQ81V2` (Admin):
 - [ ] **Custom channel group "AI Assistants"**: condition Session source matches regex
   `chatgpt\.com|chat\.openai\.com|claude\.ai|perplexity\.ai|gemini\.google\.com|copilot\.microsoft\.com|grok\.com|x\.ai|deepseek\.com|you\.com|phind\.com|meta\.ai`
   GA4's built-in "AI Assistant" channel recognizes only ChatGPT, Gemini, DeepSeek, Copilot and Grok — not Claude or Perplexity. Known limit: a large share of AI-referred sessions arrive with no referrer and land in Direct; this channel measures the floor, not the total.
-- [ ] **Custom dimensions** (event-scoped): `percent_scrolled`, `link_domain`, `ai_target`, `network`, `result`, `is_automated`.
+- [ ] **Custom dimensions** (event-scoped): `percent_scrolled`, `link_domain`, `ai_target`, `network`, `result`, `is_automated`, plus the assistant's `answered`, `escalated`, `truncated`, `from_api`, `status` and `href`. Without these registered the assistant events still arrive, but their parameters cannot be used in any report.
+- [ ] **Re-verify `window.gtag` after the GTM swap.** `widget.js` calls `track()` only `if (typeof window.gtag === 'function')`, and fails silently otherwise. That global is provided by `integrations.ga4` today and should still be provided by GTM's Google tag, but it is exactly the kind of silent break this setup has already produced once — check `typeof window.gtag` in the console on a published page after the swap lands.
 - [ ] **Explorations**: (a) free-form exploration with Page path + Exits for exit pages (GA4 has no standard exit report); (b) reverse Path exploration for drop-off journeys.
 
 Already answered by standard reports, no setup needed:
@@ -92,4 +96,4 @@ Cloudflare Analytics (total requests) vs GA4 (sessions) also gives a rough overa
 - **JS-capable agentic browsers** (Comet, Atlas, computer-use agents) execute the GA4 tag and count as humans; `is_automated` catches only naive automation.
 - **MCP query content** — not MCP volume. Requests to `https://docs.celo.org/mcp` *do* traverse Cloudflare (they return `cf-ray`, `cf-cache-status: DYNAMIC`), so request volume is visible in Cloudflare's HTTP analytics filtered by path. They are invisible to GA4, which needs JavaScript. What no layer here can show is **what was asked**: the question text, which tool was called, whether the answer cited anything.
 
-  Mintlify's own dashboard would cover part of that, but it needs the Pro plan ($450/mo), which #2250 evaluated and declined — the site was previously on Pro and deliberately moved to Starter. The intended source of query-level signal is instead the in-page assistant (#2286), which can log its own questions. That telemetry does not exist yet, so the docs-gap loop the assistant was chosen for is not closed.
+  Mintlify's own dashboard would cover part of that, but it needs the Pro plan ($450/mo), which #2250 evaluated and declined — the site was previously on Pro and deliberately moved to Starter. Query-level signal comes from the in-page assistant instead, and it is already implemented on both sides (see below).