From 229f99995c8035f45492986af0a297fd561adc82 Mon Sep 17 00:00:00 2001
From: Ray Clanan <115944+rclanan@users.noreply.github.com>
Date: Fri, 16 Oct 2026 10:20:47 -0400
Subject: [PATCH] feat(marketing): add PostHog analytics with AI-referral
 tagging

Load public/analytics.js (deferred) from the shared head block so every
generated page gets it. It initializes PostHog cookieless, without
session recording or input autocapture, and tags visits referred by AI
assistants with an ai_referral_landing event and an ai_referrer super
property.

The committed file keeps an inert placeholder key; build:site injects
POSTHOG_KEY from the environment and the deploy workflow passes the
POSTHOG_KEY secret. The privacy page now describes the analytics, and
the verify workflow runs the new node:test suite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/deploy-pages.yml            |   3 +
 .github/workflows/verify-pages-build.yml      |   1 +
 404.html                                      |   1 +
 README.md                                     |  13 +
 compare-mockserver.html                       |   1 +
 comparisons.html                              |   1 +
 contact.html                                  |   1 +
 engineering-notes.html                        |   1 +
 faq.html                                      |   1 +
 index.html                                    |   1 +
 note-announcing-v1.html                       |   1 +
 ...drift-detection-and-contract-alerting.html |   1 +
 note-client-generation-tradeoffs.html         |   1 +
 note-cloud-launch.html                        |   1 +
 note-conformance-maturity.html                |   1 +
 note-conformance-testing.html                 |   1 +
 note-cost-cap-design.html                     |   1 +
 note-fault-injection-patterns.html            |   1 +
 note-grpc-dynamic-routing-release.html        |   1 +
 note-grpc-mocking-in-ci.html                  |   1 +
 note-migration-from-static-fixtures.html      |   1 +
 note-mocking-kafka-without-broker.html        |   1 +
 ...rget-conformance-and-real-world-specs.html |   1 +
 note-our-saas-infrastructure.html             |   1 +
 note-release-cadence-and-risk.html            |   1 +
 note-reliability-update-march-2026.html       |   1 +
 ...ability-updates-conformance-and-admin.html |   1 +
 note-scenario-switching.html                  |   1 +
 note-security-guardrails-v0-2x.html           |   1 +
 note-spec-driven-openapi-conformance.html     |   1 +
 note-testing-failure-paths.html               |   1 +
 note-v0-1-3-protocol-expansion.html           |   1 +
 note-v0-2-0-client-generation.html            |   1 +
 note-v0-2-3-bug-fixes.html                    |   1 +
 note-v0-2-4-client-fixes.html                 |   1 +
 note-v0-2-5-enterprise-security.html          |   1 +
 note-v0-2-6-security-infrastructure.html      |   1 +
 note-v0-2-7-api-sync-tcp.html                 |   1 +
 note-v0-3-227-release.html                    |   1 +
 note-v0-3-migration-playbook.html             |   1 +
 note-vs-postman-mock.html                     |   1 +
 note-wafbench-security-hardening.html         |   1 +
 note-wafbench-sqli-detection.html             |   1 +
 note-wasm-plugins.html                        |   1 +
 note-when-wiremock-isnt-enough.html           |   1 +
 note-why-multi-protocol.html                  |   1 +
 package.json                                  |   3 +-
 pricing.html                                  |   1 +
 privacy.html                                  |  17 +-
 public/analytics.js                           | 227 ++++++++++++++++++
 scripts/analytics.test.js                     | 188 +++++++++++++++
 scripts/build-pages.js                        |  18 ++
 src/pages/privacy.html                        |  16 +-
 support.html                                  |   1 +
 trust.html                                    |   1 +
 vs/beeceptor.html                             |   1 +
 vs/bruno.html                                 |   1 +
 vs/microcks.html                              |   1 +
 vs/mockoon.html                               |   1 +
 vs/postman-mock.html                          |   1 +
 vs/wiremock.html                              |   1 +
 61 files changed, 525 insertions(+), 13 deletions(-)
 create mode 100644 public/analytics.js
 create mode 100644 scripts/analytics.test.js

diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
index 6756867..a572f8d 100644
--- a/.github/workflows/deploy-pages.yml
+++ b/.github/workflows/deploy-pages.yml
@@ -32,6 +32,9 @@ jobs:
       - run: npm ci
       - run: npm run build:css
       - run: npm run build:site
+        env:
+          # PostHog project key (public by design). Unset = analytics stays off.
+          POSTHOG_KEY: ${{ secrets.POSTHOG_KEY }}
 
       - uses: actions/upload-pages-artifact@v3
         with:
diff --git a/.github/workflows/verify-pages-build.yml b/.github/workflows/verify-pages-build.yml
index a221093..507d8ac 100644
--- a/.github/workflows/verify-pages-build.yml
+++ b/.github/workflows/verify-pages-build.yml
@@ -22,5 +22,6 @@ jobs:
       - run: npm run build:css
       - run: npm run build:pages
       - run: npm run build:site
+      - run: npm test
       - run: npm run check:links -- --internal-only
       - run: git diff --exit-code
diff --git a/404.html b/404.html
index 971e8e3..7257490 100644
--- a/404.html
+++ b/404.html
@@ -17,6 +17,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/README.md b/README.md
index 4582ab1..6c76759 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,19 @@ node scripts/build-pages.js --force    # build and overwrite all root files (los
 If `--check` reports drift, port the root edits back into `src/pages/` before
 running the build, so future builds stay idempotent.
 
+## Analytics
+
+`public/analytics.js` loads PostHog (US cloud) on every page through the shared head
+block in `scripts/build-pages.js`, and tags visits referred by AI assistants (ChatGPT,
+Perplexity, Claude, Gemini, Copilot, Meta AI, Grok, DeepSeek, Mistral, You.com, Phind)
+with an `ai_referral_landing` event and an `ai_referrer` property. It is cookieless and
+does not record sessions or capture form input.
+
+The committed file keeps the placeholder `"__POSTHOG_KEY__"`, which leaves analytics off.
+`npm run build:site` swaps in the `POSTHOG_KEY` environment variable when it is set; the
+deploy workflow passes the `POSTHOG_KEY` repository secret. Run `npm test` to check the
+classifier and the build injection.
+
 ## Deployment
 
 This site is deployed using GitHub Pages:
diff --git a/compare-mockserver.html b/compare-mockserver.html
index 77a81a2..c084fd7 100644
--- a/compare-mockserver.html
+++ b/compare-mockserver.html
@@ -35,6 +35,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/comparisons.html b/comparisons.html
index 17c4f9a..2384f7e 100644
--- a/comparisons.html
+++ b/comparisons.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/contact.html b/contact.html
index d800359..1abbeff 100644
--- a/contact.html
+++ b/contact.html
@@ -23,6 +23,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/engineering-notes.html b/engineering-notes.html
index b6c7779..dfed8a5 100644
--- a/engineering-notes.html
+++ b/engineering-notes.html
@@ -16,6 +16,7 @@
     <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/faq.html b/faq.html
index f33848f..320964d 100644
--- a/faq.html
+++ b/faq.html
@@ -10,6 +10,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/index.html b/index.html
index 1b9861a..a00cc5a 100644
--- a/index.html
+++ b/index.html
@@ -82,6 +82,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-announcing-v1.html b/note-announcing-v1.html
index 3ff5a35..5a3effa 100644
--- a/note-announcing-v1.html
+++ b/note-announcing-v1.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-api-drift-detection-and-contract-alerting.html b/note-api-drift-detection-and-contract-alerting.html
index d8a7e92..bcd2b3a 100644
--- a/note-api-drift-detection-and-contract-alerting.html
+++ b/note-api-drift-detection-and-contract-alerting.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-client-generation-tradeoffs.html b/note-client-generation-tradeoffs.html
index 17827f9..427531e 100644
--- a/note-client-generation-tradeoffs.html
+++ b/note-client-generation-tradeoffs.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-cloud-launch.html b/note-cloud-launch.html
index 36dfc89..610c1a5 100644
--- a/note-cloud-launch.html
+++ b/note-cloud-launch.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-conformance-maturity.html b/note-conformance-maturity.html
index 7b5b91c..569502f 100644
--- a/note-conformance-maturity.html
+++ b/note-conformance-maturity.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-conformance-testing.html b/note-conformance-testing.html
index 7818141..63e191c 100644
--- a/note-conformance-testing.html
+++ b/note-conformance-testing.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-cost-cap-design.html b/note-cost-cap-design.html
index 803c8a9..5ec1529 100644
--- a/note-cost-cap-design.html
+++ b/note-cost-cap-design.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-fault-injection-patterns.html b/note-fault-injection-patterns.html
index 4d1b680..8cea3a4 100644
--- a/note-fault-injection-patterns.html
+++ b/note-fault-injection-patterns.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-grpc-dynamic-routing-release.html b/note-grpc-dynamic-routing-release.html
index 1731dce..39e9fe1 100644
--- a/note-grpc-dynamic-routing-release.html
+++ b/note-grpc-dynamic-routing-release.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-grpc-mocking-in-ci.html b/note-grpc-mocking-in-ci.html
index 0dbe9dd..821df3d 100644
--- a/note-grpc-mocking-in-ci.html
+++ b/note-grpc-mocking-in-ci.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-migration-from-static-fixtures.html b/note-migration-from-static-fixtures.html
index 1d4cb20..28141fb 100644
--- a/note-migration-from-static-fixtures.html
+++ b/note-migration-from-static-fixtures.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-mocking-kafka-without-broker.html b/note-mocking-kafka-without-broker.html
index 9990535..c73c721 100644
--- a/note-mocking-kafka-without-broker.html
+++ b/note-mocking-kafka-without-broker.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-multi-target-conformance-and-real-world-specs.html b/note-multi-target-conformance-and-real-world-specs.html
index c9f03a3..7cb7464 100644
--- a/note-multi-target-conformance-and-real-world-specs.html
+++ b/note-multi-target-conformance-and-real-world-specs.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-our-saas-infrastructure.html b/note-our-saas-infrastructure.html
index a3e3870..2cd9988 100644
--- a/note-our-saas-infrastructure.html
+++ b/note-our-saas-infrastructure.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-release-cadence-and-risk.html b/note-release-cadence-and-risk.html
index 80c8150..7632dcf 100644
--- a/note-release-cadence-and-risk.html
+++ b/note-release-cadence-and-risk.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-reliability-update-march-2026.html b/note-reliability-update-march-2026.html
index 75db1a5..621fdba 100644
--- a/note-reliability-update-march-2026.html
+++ b/note-reliability-update-march-2026.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-reliability-updates-conformance-and-admin.html b/note-reliability-updates-conformance-and-admin.html
index 04dfe2d..5d7dcf4 100644
--- a/note-reliability-updates-conformance-and-admin.html
+++ b/note-reliability-updates-conformance-and-admin.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-scenario-switching.html b/note-scenario-switching.html
index c57d091..2fc68e3 100644
--- a/note-scenario-switching.html
+++ b/note-scenario-switching.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-security-guardrails-v0-2x.html b/note-security-guardrails-v0-2x.html
index 6e0fa93..04e1dec 100644
--- a/note-security-guardrails-v0-2x.html
+++ b/note-security-guardrails-v0-2x.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-spec-driven-openapi-conformance.html b/note-spec-driven-openapi-conformance.html
index dcd94e2..d3df5e7 100644
--- a/note-spec-driven-openapi-conformance.html
+++ b/note-spec-driven-openapi-conformance.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-testing-failure-paths.html b/note-testing-failure-paths.html
index e9d49c6..088ebc7 100644
--- a/note-testing-failure-paths.html
+++ b/note-testing-failure-paths.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-1-3-protocol-expansion.html b/note-v0-1-3-protocol-expansion.html
index f860a45..cb503e3 100644
--- a/note-v0-1-3-protocol-expansion.html
+++ b/note-v0-1-3-protocol-expansion.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-2-0-client-generation.html b/note-v0-2-0-client-generation.html
index bb5f4cc..6e21d80 100644
--- a/note-v0-2-0-client-generation.html
+++ b/note-v0-2-0-client-generation.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-2-3-bug-fixes.html b/note-v0-2-3-bug-fixes.html
index 5c8b1fb..9833857 100644
--- a/note-v0-2-3-bug-fixes.html
+++ b/note-v0-2-3-bug-fixes.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-2-4-client-fixes.html b/note-v0-2-4-client-fixes.html
index 94bf6c4..b7d3136 100644
--- a/note-v0-2-4-client-fixes.html
+++ b/note-v0-2-4-client-fixes.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-2-5-enterprise-security.html b/note-v0-2-5-enterprise-security.html
index 1ae9344..c972f38 100644
--- a/note-v0-2-5-enterprise-security.html
+++ b/note-v0-2-5-enterprise-security.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-2-6-security-infrastructure.html b/note-v0-2-6-security-infrastructure.html
index c22be52..da9b8d8 100644
--- a/note-v0-2-6-security-infrastructure.html
+++ b/note-v0-2-6-security-infrastructure.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-2-7-api-sync-tcp.html b/note-v0-2-7-api-sync-tcp.html
index 86c1fc9..856bfb2 100644
--- a/note-v0-2-7-api-sync-tcp.html
+++ b/note-v0-2-7-api-sync-tcp.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-3-227-release.html b/note-v0-3-227-release.html
index 3b1c4ed..a2a2975 100644
--- a/note-v0-3-227-release.html
+++ b/note-v0-3-227-release.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-v0-3-migration-playbook.html b/note-v0-3-migration-playbook.html
index 355ec76..dc43cdb 100644
--- a/note-v0-3-migration-playbook.html
+++ b/note-v0-3-migration-playbook.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-vs-postman-mock.html b/note-vs-postman-mock.html
index 04d48f2..01da830 100644
--- a/note-vs-postman-mock.html
+++ b/note-vs-postman-mock.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-wafbench-security-hardening.html b/note-wafbench-security-hardening.html
index 6f63edd..7c7ee57 100644
--- a/note-wafbench-security-hardening.html
+++ b/note-wafbench-security-hardening.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-wafbench-sqli-detection.html b/note-wafbench-sqli-detection.html
index 5b206f6..1ee4afb 100644
--- a/note-wafbench-sqli-detection.html
+++ b/note-wafbench-sqli-detection.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-wasm-plugins.html b/note-wasm-plugins.html
index b2056a9..c87524c 100644
--- a/note-wasm-plugins.html
+++ b/note-wasm-plugins.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-when-wiremock-isnt-enough.html b/note-when-wiremock-isnt-enough.html
index f262c94..f1cf812 100644
--- a/note-when-wiremock-isnt-enough.html
+++ b/note-when-wiremock-isnt-enough.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/note-why-multi-protocol.html b/note-why-multi-protocol.html
index 1354ff6..252c3c4 100644
--- a/note-why-multi-protocol.html
+++ b/note-why-multi-protocol.html
@@ -14,6 +14,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/package.json b/package.json
index 636089b..22a6cca 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,8 @@
     "build:pages": "node ./scripts/build-pages.js",
     "build:site": "node ./scripts/build-pages.js dist",
     "sync:shells": "npm run build:pages",
-    "check:links": "node ./scripts/check-links.mjs"
+    "check:links": "node ./scripts/check-links.mjs",
+    "test": "node --test scripts/analytics.test.js"
   },
   "devDependencies": {
     "tailwindcss": "3.4.17"
diff --git a/pricing.html b/pricing.html
index 1f943a6..6915056 100644
--- a/pricing.html
+++ b/pricing.html
@@ -34,6 +34,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/privacy.html b/privacy.html
index 97e0c49..ba5bf31 100644
--- a/privacy.html
+++ b/privacy.html
@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Privacy — MockForge</title>
-    <meta name="description" content="What the mockforge.dev marketing site collects: no analytics or tracking scripts, just a local theme preference in localStorage. No accounts, forms, or ads on this site." />
+    <meta name="description" content="What the mockforge.dev marketing site collects: cookieless PostHog analytics and a local theme preference. No accounts, forms, or ads on this site." />
     <meta name="robots" content="noindex, follow" />
 
     <meta property="og:title" content="Privacy — MockForge" />
@@ -23,6 +23,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
@@ -164,7 +165,7 @@
         <h1 class="mt-3 text-4xl font-semibold tracking-tight text-brand-dark dark:text-white">
           What this website collects
         </h1>
-        <p class="mt-3 text-sm text-text-secondary">Last updated: September 27, 2026</p>
+        <p class="mt-3 text-sm text-text-secondary">Last updated: October 16, 2026</p>
         <p class="mt-4 text-lg text-text-secondary leading-relaxed">
           This policy covers the public marketing site at mockforge.dev. It is intentionally short
           because the site is static: it has no user accounts, no comment forms, no advertising,
@@ -175,7 +176,10 @@ <h1 class="mt-3 text-4xl font-semibold tracking-tight text-brand-dark dark:text-
           <div>
             <h2 class="text-xl font-semibold text-brand-dark">Analytics</h2>
             <p class="mt-2 text-text-secondary leading-relaxed">
-              This site does not run analytics or tracking scripts and sets no cookies. Like any
+              This site uses PostHog to count page views and link clicks in aggregate, including
+              whether a visit came from an AI assistant such as ChatGPT, Perplexity, or Claude. It
+              runs without cookies, does not keep an identifier across visits, does not record
+              sessions, and does not capture form input. The site sets no cookies. Like any
               web server, our static host (GitHub Pages) may keep standard request logs such as IP
               address and user agent for security and abuse prevention. Web fonts are served by
               Google Fonts, which receives a normal request when a page loads.
@@ -185,9 +189,10 @@ <h2 class="text-xl font-semibold text-brand-dark">Analytics</h2>
           <div>
             <h2 class="text-xl font-semibold text-brand-dark">Local storage</h2>
             <p class="mt-2 text-text-secondary leading-relaxed">
-              The only value this site stores in your browser is a single
-              <code>theme</code> key in localStorage that remembers whether you chose light or
-              dark mode. It never leaves your device and is not shared with anyone.
+              This site stores a <code>theme</code> key in localStorage that remembers whether you
+              chose light or dark mode; it never leaves your device. When a visit comes from an AI
+              assistant, an <code>ai_referrer</code> key in sessionStorage notes which one so the
+              analytics above can attribute the visit; it is cleared when you close the tab.
             </p>
           </div>
 
diff --git a/public/analytics.js b/public/analytics.js
new file mode 100644
index 0000000..771e25a
--- /dev/null
+++ b/public/analytics.js
@@ -0,0 +1,227 @@
+/*
+ * PostHog analytics + AI-referral tagging.
+ *
+ * Inert until POSTHOG_KEY holds a real project key (PostHog project keys are
+ * public by design; they only allow sending events). While the value is the
+ * placeholder, this file loads nothing and sends nothing.
+ *
+ * Privacy: cookieless (persistence: 'memory'), no session recording, and
+ * autocapture limited to links, buttons and form submits (never input fields).
+ * The only browser storage used is one sessionStorage key that remembers which
+ * AI assistant referred this tab, so later pages in the same visit keep the tag.
+ */
+(function (root, factory) {
+  var api = factory();
+  if (typeof module === 'object' && module.exports) {
+    module.exports = api;
+  } else if (root && root.document) {
+    api.boot(root);
+  }
+})(typeof window !== 'undefined' ? window : this, function () {
+  'use strict';
+
+  var POSTHOG_KEY = "__POSTHOG_KEY__";
+  var POSTHOG_API_HOST = 'https://us.i.posthog.com';
+  var POSTHOG_UI_HOST = 'https://us.posthog.com';
+  var POSTHOG_SCRIPT = 'https://us-assets.i.posthog.com/static/array.js';
+  var SESSION_KEY = 'ai_referrer';
+
+  // engine -> referrer hosts (a host also matches its subdomains).
+  var ENGINE_HOSTS = {
+    chatgpt: ['chatgpt.com', 'chat.openai.com'],
+    perplexity: ['perplexity.ai'],
+    claude: ['claude.ai'],
+    gemini: ['gemini.google.com', 'bard.google.com'],
+    copilot: ['copilot.microsoft.com'],
+    meta_ai: ['meta.ai'],
+    grok: ['grok.com', 'x.ai'],
+    deepseek: ['chat.deepseek.com'],
+    mistral: ['chat.mistral.ai'],
+    you: ['you.com'],
+    phind: ['phind.com']
+  };
+
+  // Bare utm_source values (no dot) that name an engine.
+  var UTM_ALIASES = {
+    chatgpt: 'chatgpt',
+    openai: 'chatgpt',
+    perplexity: 'perplexity',
+    claude: 'claude',
+    gemini: 'gemini',
+    bard: 'gemini',
+    copilot: 'copilot',
+    meta_ai: 'meta_ai',
+    metaai: 'meta_ai',
+    grok: 'grok',
+    deepseek: 'deepseek',
+    mistral: 'mistral',
+    phind: 'phind'
+  };
+
+  function hostMatches(host, domain) {
+    return host === domain || host.slice(-(domain.length + 1)) === '.' + domain;
+  }
+
+  function engineForHost(host, path) {
+    if (!host) return null;
+    host = host.toLowerCase().replace(/\.$/, '');
+    if (host === 'edgeservices.bing.com') {
+      return /^\/edgesvc\/chat/i.test(path || '') ? 'copilot' : null;
+    }
+    for (var engine in ENGINE_HOSTS) {
+      var hosts = ENGINE_HOSTS[engine];
+      for (var i = 0; i < hosts.length; i++) {
+        if (hostMatches(host, hosts[i])) return engine;
+      }
+    }
+    return null;
+  }
+
+  function engineForUtm(source) {
+    if (!source) return null;
+    var value = String(source).trim().toLowerCase();
+    if (!value) return null;
+    if (Object.prototype.hasOwnProperty.call(UTM_ALIASES, value)) return UTM_ALIASES[value];
+    var host = value.replace(/^[a-z]+:\/\//, '').replace(/^www\./, '').split(/[/?#]/)[0];
+    var path = value.replace(/^[a-z]+:\/\//, '').slice(host.length);
+    return host.indexOf('.') === -1 ? null : engineForHost(host, path);
+  }
+
+  function parseUrl(value) {
+    if (!value) return null;
+    try {
+      return new URL(String(value));
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function bareHost(host) {
+    return String(host || '').toLowerCase().replace(/^www\./, '');
+  }
+
+  function utmSource(loc) {
+    if (!loc) return null;
+    var search = loc.search != null ? loc.search : (parseUrl(loc.href) || {}).search;
+    if (!search) return null;
+    try {
+      return new URLSearchParams(search).get('utm_source');
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // classify(document.referrer, location) -> engine name | null
+  function classify(referrer, loc) {
+    var ref = parseUrl(referrer);
+    var hereHost = loc && loc.hostname ? bareHost(loc.hostname) : '';
+    if (ref && hereHost && bareHost(ref.hostname) === hereHost) return null;
+    return (ref && engineForHost(ref.hostname, ref.pathname)) || engineForUtm(utmSource(loc));
+  }
+
+  function isConfigured() {
+    return typeof POSTHOG_KEY === 'string' && /^phc_[A-Za-z0-9_-]+$/.test(POSTHOG_KEY);
+  }
+
+  function readSession(win) {
+    try {
+      return win.sessionStorage.getItem(SESSION_KEY);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function writeSession(win, value) {
+    try {
+      win.sessionStorage.setItem(SESSION_KEY, value);
+    } catch (e) {
+      /* storage blocked: tag this page only */
+    }
+  }
+
+  // Official posthog-js loader stub: queues calls until array.js arrives.
+  function loadPostHog(win) {
+    var doc = win.document;
+    var ph = win.posthog = win.posthog || [];
+    if (ph.__SV) return ph;
+    ph._i = [];
+    ph.init = function (key, config, name) {
+      function stub(target, method) {
+        var parts = method.split('.');
+        if (parts.length === 2) {
+          target = target[parts[0]];
+          method = parts[1];
+        }
+        target[method] = function () {
+          target.push([method].concat(Array.prototype.slice.call(arguments, 0)));
+        };
+      }
+      var script = doc.createElement('script');
+      script.type = 'text/javascript';
+      script.crossOrigin = 'anonymous';
+      script.async = true;
+      script.src = POSTHOG_SCRIPT;
+      var first = doc.getElementsByTagName('script')[0];
+      first.parentNode.insertBefore(script, first);
+      var instance = ph;
+      if (name !== undefined) instance = ph[name] = [];
+      else name = 'posthog';
+      instance.people = instance.people || [];
+      instance.toString = function (noStub) {
+        var label = 'posthog';
+        if (name !== 'posthog') label += '.' + name;
+        if (!noStub) label += ' (stub)';
+        return label;
+      };
+      instance.people.toString = function () {
+        return instance.toString(1) + '.people (stub)';
+      };
+      var methods = 'init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags onFeatureFlags onSessionId identify setPersonProperties group resetGroups reset get_distinct_id getGroups get_session_id alias set_config opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug'.split(' ');
+      for (var i = 0; i < methods.length; i++) stub(instance, methods[i]);
+      ph._i.push([key, config, name]);
+    };
+    ph.__SV = 1;
+    return ph;
+  }
+
+  function boot(win) {
+    if (!isConfigured()) return;
+    var posthog = loadPostHog(win);
+    posthog.init(POSTHOG_KEY, {
+      api_host: POSTHOG_API_HOST,
+      ui_host: POSTHOG_UI_HOST,
+      persistence: 'memory',
+      person_profiles: 'identified_only',
+      capture_pageview: true,
+      capture_pageleave: true,
+      disable_session_recording: true,
+      disable_surveys: true,
+      autocapture: { element_allowlist: ['a', 'button', 'form'] }
+    });
+
+    var loc = win.location;
+    var engine = classify(win.document.referrer, loc);
+    var tagged = readSession(win);
+
+    if (engine && !tagged) {
+      writeSession(win, engine);
+      var ref = parseUrl(win.document.referrer);
+      posthog.register({ ai_referrer: engine });
+      posthog.capture('ai_referral_landing', {
+        ai_engine: engine,
+        landing_path: loc.pathname,
+        referrer_host: ref ? ref.hostname : null,
+        utm_source: utmSource(loc),
+        $set_once: { initial_ai_referrer: engine }
+      });
+      if (typeof win.gtag === 'function') {
+        win.gtag('event', 'ai_referral_landing', { ai_engine: engine });
+      }
+    } else if (tagged) {
+      // Memory persistence resets per page; carry the tag through the visit.
+      posthog.register({ ai_referrer: tagged });
+    }
+  }
+
+  return { classify: classify, boot: boot, isConfigured: isConfigured };
+});
diff --git a/scripts/analytics.test.js b/scripts/analytics.test.js
new file mode 100644
index 0000000..f2f22d5
--- /dev/null
+++ b/scripts/analytics.test.js
@@ -0,0 +1,188 @@
+// Run: node --test scripts/analytics.test.js
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const { classify, isConfigured, boot } = require(path.join(__dirname, '../public/analytics.js'));
+
+const here = (href) => new URL(href);
+const site = here('https://mockforge.dev/');
+
+test('referrer hosts map to engines', () => {
+  const cases = {
+    'https://chatgpt.com/': 'chatgpt',
+    'https://chat.openai.com/c/abc': 'chatgpt',
+    'https://www.perplexity.ai/search?q=x': 'perplexity',
+    'https://claude.ai/': 'claude',
+    'https://gemini.google.com/app': 'gemini',
+    'https://bard.google.com/': 'gemini',
+    'https://copilot.microsoft.com/': 'copilot',
+    'https://edgeservices.bing.com/edgesvc/chat?x=1': 'copilot',
+    'https://www.meta.ai/': 'meta_ai',
+    'https://grok.com/': 'grok',
+    'https://x.ai/': 'grok',
+    'https://chat.deepseek.com/': 'deepseek',
+    'https://chat.mistral.ai/chat': 'mistral',
+    'https://you.com/search?q=x': 'you',
+    'https://www.phind.com/': 'phind',
+  };
+  for (const [referrer, engine] of Object.entries(cases)) {
+    assert.equal(classify(referrer, site), engine, referrer);
+  }
+});
+
+test('utm_source alone identifies the engine', () => {
+  assert.equal(classify('', here('https://mockforge.dev/?utm_source=chatgpt.com')), 'chatgpt');
+  assert.equal(classify('', here('https://mockforge.dev/?utm_source=perplexity')), 'perplexity');
+  assert.equal(classify('', here('https://mockforge.dev/?utm_source=claude.ai')), 'claude');
+  assert.equal(classify('', here('https://mockforge.dev/?utm_source=Copilot')), 'copilot');
+  assert.equal(classify('https://www.google.com/', here('https://mockforge.dev/?utm_source=chatgpt.com')), 'chatgpt');
+});
+
+test('non-AI and lookalike sources are not tagged', () => {
+  assert.equal(classify('', site), null);
+  assert.equal(classify('https://www.google.com/search?q=x', site), null);
+  assert.equal(classify('https://www.bing.com/', site), null);
+  assert.equal(classify('https://edgeservices.bing.com/other', site), null);
+  assert.equal(classify('https://google.com/', site), null);
+  assert.equal(classify('https://max.ai/', site), null);
+  assert.equal(classify('https://notchatgpt.com/', site), null);
+  assert.equal(classify('https://chatgpt.com.evil.example/', site), null);
+  assert.equal(classify('not a url', site), null);
+  assert.equal(classify('', here('https://mockforge.dev/?utm_source=newsletter')), null);
+  assert.equal(classify('', here('https://mockforge.dev/?utm_source=you')), null);
+});
+
+test('same-site navigation is never tagged', () => {
+  assert.equal(classify('https://mockforge.dev/about.html', site), null);
+  assert.equal(classify('https://www.mockforge.dev/', site), null);
+  assert.equal(classify('https://mockforge.dev/', here('https://mockforge.dev/x?utm_source=chatgpt.com')), null);
+});
+
+test('placeholder key keeps the script inert', () => {
+  assert.equal(isConfigured(), false);
+  const win = { document: { referrer: 'https://chatgpt.com/' }, location: site };
+  boot(win);
+  assert.equal(win.posthog, undefined);
+});
+
+function runInBrowser(href, referrer, storage) {
+  const fs = require('node:fs');
+  const vm = require('node:vm');
+  const source = fs
+    .readFileSync(path.join(__dirname, '../public/analytics.js'), 'utf8')
+    .replace('"__POSTHOG' + '_KEY__"', '"phc_testkey"');
+  const scripts = [];
+  const gtagCalls = [];
+  const win = {
+    URL,
+    URLSearchParams,
+    location: new URL(href),
+    sessionStorage: storage,
+    gtag: (...args) => gtagCalls.push(args),
+    document: {
+      referrer,
+      createElement: () => ({}),
+      getElementsByTagName: () => [{ parentNode: { insertBefore: (el) => scripts.push(el) } }],
+    },
+  };
+  win.window = win;
+  vm.runInNewContext(source, win);
+  const calls = win.posthog.filter((entry) => Array.isArray(entry));
+  return { win, scripts, gtagCalls, calls };
+}
+
+function memoryStorage() {
+  const data = new Map();
+  return { getItem: (k) => (data.has(k) ? data.get(k) : null), setItem: (k, v) => data.set(k, String(v)) };
+}
+
+test('configured key tags an AI landing once per session', () => {
+  const storage = memoryStorage();
+  const first = runInBrowser('https://mockforge.dev/pricing?utm_source=chatgpt.com', 'https://chatgpt.com/', storage);
+  assert.equal(first.scripts[0].src, 'https://us-assets.i.posthog.com/static/array.js');
+  const [key, config] = first.win.posthog._i[0];
+  assert.equal(key, 'phc_testkey');
+  assert.equal(config.persistence, 'memory');
+  assert.equal(config.disable_session_recording, true);
+  const register = first.calls.find((c) => c[0] === 'register');
+  assert.deepEqual({ ...register[1] }, { ai_referrer: 'chatgpt' });
+  const capture = first.calls.find((c) => c[0] === 'capture');
+  assert.equal(capture[1], 'ai_referral_landing');
+  assert.equal(capture[2].ai_engine, 'chatgpt');
+  assert.equal(capture[2].landing_path, '/pricing');
+  assert.equal(capture[2].referrer_host, 'chatgpt.com');
+  assert.equal(capture[2].utm_source, 'chatgpt.com');
+  assert.equal(capture[2].$set_once.initial_ai_referrer, 'chatgpt');
+  assert.equal(first.gtagCalls.length, 1);
+  assert.equal(first.gtagCalls[0][1], 'ai_referral_landing');
+
+  const second = runInBrowser('https://mockforge.dev/about', 'https://mockforge.dev/pricing', storage);
+  assert.equal(second.calls.some((c) => c[0] === 'capture'), false);
+  assert.equal(second.calls.find((c) => c[0] === 'register')[1].ai_referrer, 'chatgpt');
+});
+
+test('blocked sessionStorage still tags the landing page', () => {
+  const blocked = { getItem() { throw new Error('blocked'); }, setItem() { throw new Error('blocked'); } };
+  const run = runInBrowser('https://mockforge.dev/', 'https://www.perplexity.ai/', blocked);
+  assert.equal(run.calls.find((c) => c[0] === 'capture')[2].ai_engine, 'perplexity');
+});
+
+test('non-AI visit sends no AI events', () => {
+  const run = runInBrowser('https://mockforge.dev/', 'https://www.google.com/', memoryStorage());
+  assert.equal(run.calls.some((c) => c[0] === 'capture' || c[0] === 'register'), false);
+  assert.equal(run.gtagCalls.length, 0);
+});
+
+test('site build includes analytics on every page and injects POSTHOG_KEY', () => {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const { execFileSync } = require('node:child_process');
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mockforge-site-'));
+  try {
+    execFileSync(process.execPath, [path.join(__dirname, 'build-pages.js'), outDir], {
+      env: { ...process.env, POSTHOG_KEY: 'phc_buildtestkey' },
+      stdio: 'pipe',
+    });
+    const injected = fs.readFileSync(path.join(outDir, 'public', 'analytics.js'), 'utf8');
+    assert.match(injected, /var POSTHOG_KEY = "phc_buildtestkey";/);
+    const source = fs.readFileSync(path.join(__dirname, '..', 'public', 'analytics.js'), 'utf8');
+    assert.match(source, /var POSTHOG_KEY = "__POSTHOG_KEY__";/, 'committed file keeps the placeholder');
+
+    const srcPages = fs.readdirSync(path.join(__dirname, '..', 'src', 'pages')).filter((f) => f.endsWith('.html'));
+    let checked = 0;
+    const walk = (dir) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.name.endsWith('.html')) {
+          const html = fs.readFileSync(full, 'utf8');
+          if (html.includes('http-equiv="refresh"')) continue; // generated redirect stubs
+          const count = (html.match(/<script src="\/public\/analytics\.js" defer><\/script>/g) || []).length;
+          assert.equal(count, 1, `${path.relative(outDir, full)} must include analytics.js once`);
+          checked += 1;
+        }
+      }
+    };
+    walk(outDir);
+    assert.equal(checked, srcPages.length);
+  } finally {
+    fs.rmSync(outDir, { recursive: true, force: true });
+  }
+});
+
+test('site build rejects a malformed POSTHOG_KEY', () => {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const { spawnSync } = require('node:child_process');
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mockforge-site-'));
+  try {
+    const run = spawnSync(process.execPath, [path.join(__dirname, 'build-pages.js'), outDir], {
+      env: { ...process.env, POSTHOG_KEY: '"; alert(1); "' },
+      stdio: 'pipe',
+    });
+    assert.notEqual(run.status, 0);
+  } finally {
+    fs.rmSync(outDir, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/build-pages.js b/scripts/build-pages.js
index 192b2e3..70e731e 100644
--- a/scripts/build-pages.js
+++ b/scripts/build-pages.js
@@ -31,6 +31,7 @@ function renderSharedHeadBlock(includeOrgLd = true) {
   return `
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
@@ -668,6 +669,23 @@ if (outputRoot !== projectRoot && !flagCheck) {
   }
 
   fs.writeFileSync(path.join(outputRoot, 'public', 'sitemap.xml'), sitemap);
+
+  // PostHog project key comes from the deploy environment (POSTHOG_KEY secret)
+  // so the committed source keeps the inert placeholder. Unset = analytics off.
+  const posthogKey = (process.env.POSTHOG_KEY || '').trim();
+  if (posthogKey) {
+    if (!/^phc_[A-Za-z0-9_-]+$/.test(posthogKey)) {
+      throw new Error('POSTHOG_KEY must be a PostHog project key (phc_...)');
+    }
+    const analyticsPath = path.join(outputRoot, 'public', 'analytics.js');
+    const analytics = fs.readFileSync(analyticsPath, 'utf8');
+    const placeholder = '"__POSTHOG_KEY__"';
+    if (analytics.split(placeholder).length !== 2) {
+      throw new Error(`Expected exactly one ${placeholder} in public/analytics.js`);
+    }
+    fs.writeFileSync(analyticsPath, analytics.replace(placeholder, JSON.stringify(posthogKey)));
+    console.log('Injected POSTHOG_KEY into public/analytics.js');
+  }
   fs.writeFileSync(path.join(outputRoot, 'sitemap.xml'), sitemap);
 
   // Serve agent/SEO discovery files from the dist root, not only under
diff --git a/src/pages/privacy.html b/src/pages/privacy.html
index 3ccf8f4..f08a72f 100644
--- a/src/pages/privacy.html
+++ b/src/pages/privacy.html
@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Privacy — MockForge</title>
-    <meta name="description" content="What the mockforge.dev marketing site collects: no analytics or tracking scripts, just a local theme preference in localStorage. No accounts, forms, or ads on this site." />
+    <meta name="description" content="What the mockforge.dev marketing site collects: cookieless PostHog analytics and a local theme preference. No accounts, forms, or ads on this site." />
     <meta name="robots" content="noindex, follow" />
 
     <meta property="og:title" content="Privacy — MockForge" />
@@ -32,7 +32,7 @@
         <h1 class="mt-3 text-4xl font-semibold tracking-tight text-brand-dark dark:text-white">
           What this website collects
         </h1>
-        <p class="mt-3 text-sm text-text-secondary">Last updated: September 27, 2026</p>
+        <p class="mt-3 text-sm text-text-secondary">Last updated: October 16, 2026</p>
         <p class="mt-4 text-lg text-text-secondary leading-relaxed">
           This policy covers the public marketing site at mockforge.dev. It is intentionally short
           because the site is static: it has no user accounts, no comment forms, no advertising,
@@ -43,7 +43,10 @@ <h1 class="mt-3 text-4xl font-semibold tracking-tight text-brand-dark dark:text-
           <div>
             <h2 class="text-xl font-semibold text-brand-dark">Analytics</h2>
             <p class="mt-2 text-text-secondary leading-relaxed">
-              This site does not run analytics or tracking scripts and sets no cookies. Like any
+              This site uses PostHog to count page views and link clicks in aggregate, including
+              whether a visit came from an AI assistant such as ChatGPT, Perplexity, or Claude. It
+              runs without cookies, does not keep an identifier across visits, does not record
+              sessions, and does not capture form input. The site sets no cookies. Like any
               web server, our static host (GitHub Pages) may keep standard request logs such as IP
               address and user agent for security and abuse prevention. Web fonts are served by
               Google Fonts, which receives a normal request when a page loads.
@@ -53,9 +56,10 @@ <h2 class="text-xl font-semibold text-brand-dark">Analytics</h2>
           <div>
             <h2 class="text-xl font-semibold text-brand-dark">Local storage</h2>
             <p class="mt-2 text-text-secondary leading-relaxed">
-              The only value this site stores in your browser is a single
-              <code>theme</code> key in localStorage that remembers whether you chose light or
-              dark mode. It never leaves your device and is not shared with anyone.
+              This site stores a <code>theme</code> key in localStorage that remembers whether you
+              chose light or dark mode; it never leaves your device. When a visit comes from an AI
+              assistant, an <code>ai_referrer</code> key in sessionStorage notes which one so the
+              analytics above can attribute the visit; it is cleared when you close the tab.
             </p>
           </div>
 
diff --git a/support.html b/support.html
index 1c5fcfb..f3763e2 100644
--- a/support.html
+++ b/support.html
@@ -10,6 +10,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/trust.html b/trust.html
index dc78a60..5f0f4e6 100644
--- a/trust.html
+++ b/trust.html
@@ -33,6 +33,7 @@
 
     <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/vs/beeceptor.html b/vs/beeceptor.html
index 9d04dae..7c253e1 100644
--- a/vs/beeceptor.html
+++ b/vs/beeceptor.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/vs/bruno.html b/vs/bruno.html
index a927e6a..3cee1a2 100644
--- a/vs/bruno.html
+++ b/vs/bruno.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/vs/microcks.html b/vs/microcks.html
index 1bce0c9..ca45d8c 100644
--- a/vs/microcks.html
+++ b/vs/microcks.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/vs/mockoon.html b/vs/mockoon.html
index 7529087..a5bb11b 100644
--- a/vs/mockoon.html
+++ b/vs/mockoon.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/vs/postman-mock.html b/vs/postman-mock.html
index 769cf0e..a67d9a4 100644
--- a/vs/postman-mock.html
+++ b/vs/postman-mock.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {
diff --git a/vs/wiremock.html b/vs/wiremock.html
index 763c339..e674416 100644
--- a/vs/wiremock.html
+++ b/vs/wiremock.html
@@ -10,6 +10,7 @@
 <link rel="stylesheet" href="/public/vendor/phosphor/phosphor.css" />
 <link rel="stylesheet" href="/public/styles.css" />
     <link rel="alternate" type="application/rss+xml" title="MockForge Engineering Notes" href="/rss.xml" />
+    <script src="/public/analytics.js" defer></script>
     <script>
       (function () {
         try {