webmaxru
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 59 additions & 2 deletions b/‎README.md‎
Lines changed: 59 additions & 2 deletions
diff --git a/‎analytics/analytics.entry.js‎
Lines changed: 137 additions & 0 deletions b/‎analytics/analytics.entry.js‎
Lines changed: 137 additions & 0 deletions
@@ -1,3 +1,6 @@
+# Node (analytics beacon build tooling)
+node_modules/
+
 # Python
 .venv/
 __pycache__/
 
@@ -164,9 +164,15 @@ site/
   generate.py         # scaffolds the site from content/toc.yml
   index.html          # generated
   chapters/*.html     # generated: one page per chapter in toc.yml
-  assets/             # style.css + app.js
+  assets/             # style.css + app.js + analytics.js (built beacon)
+analytics/
+  analytics.entry.js  # cookieless App Insights beacon source (bundled → site/assets/analytics.js)
+azure/
+  dashboard.json      # Portal engagement dashboard (ARM template)
+package.json          # analytics build tooling (esbuild bundle + report command)
 scripts/
   run-fleet.ps1       # convenience launcher
+  report.ps1          # engagement report (PowerShell)
 ```
 
 > The book content itself (`content/research/`, `examples/`, generated `site/` pages) is produced by
@@ -205,7 +211,58 @@ gh aw compile examples/<chapter>/<workflow>.md
 
 ---
 
-## Chapter arc
+## Privacy-friendly analytics (cookieless RUM)
+
+The published site is instrumented with **cookieless Real User Monitoring** via Azure Application
+Insights, using [`@webmaxru/cookieless-insights`](https://www.npmjs.com/package/@webmaxru/cookieless-insights).
+It uses **no cookies, no local/session storage, and no persistent identifier** — so there is **no
+consent banner** — and stays inside Azure's **free tier** (workspace-based, 30-day retention,
+0.16 GB/day cap). Telemetry is sent with the browser **beacon** transport (`navigator.sendBeacon`).
+
+**How it's wired**
+
+- `analytics/analytics.entry.js` is the beacon source — it initializes tracking, records an
+  automatic **page view**, and wires **key interactions** (theme change, sidebar toggle, code copy,
+  in-page section nav, internal/outbound link clicks, "opened via shared link", and debounced
+  input changes for any sliders/typing). It is bundled to `site/assets/analytics.js` with esbuild:
+  ```powershell
+  npm ci
+  npm run build:analytics
+  ```
+- The Application Insights **connection string is a public client key**, injected at **build time**,
+  never committed as source. `site/generate.py` reads the `APPINSIGHTS_CONNECTION_STRING`
+  environment variable and embeds it into each page's `<head>` as
+  `window.__APPINSIGHTS_CONNECTION_STRING__`; the beacon reads that global. The committed HTML
+  carries an **empty** string (a safe no-op).
+- In CI (`.github/workflows/deploy-pages.yml`) the value comes from the repository **Actions
+  variable** `APPINSIGHTS_CONNECTION_STRING` (Settings → Secrets and variables → Actions →
+  Variables — *not* a secret), and is injected only into the `gh-pages` build.
+
+**Kill switch (one line).** Flip the constant at the top of `analytics/analytics.entry.js` and
+rebuild:
+
+```js
+const ANALYTICS_ENABLED = false; // disables all telemetry
+```
+
+Clearing the `APPINSIGHTS_CONNECTION_STRING` repo variable (empty string) also disables tracking on
+the next deploy — `init()` self-disables when the connection string is empty.
+
+**Engagement report & dashboard**
+
+```powershell
+# print engagement (page views, sessions, per-visit dwell, key events, top pages, geo, browser/OS)
+npm run report                       # wraps the command below and opens the Portal dashboard
+npx cookieless-insights report --resource-group is-ai-native-rg --app-insights aw-book-ai --days 30
+# PowerShell equivalent
+./scripts/report.ps1 -ResourceGroup is-ai-native-rg -AppInsights aw-book-ai
+```
+
+The Azure Portal **engagement dashboard** (`azure/dashboard.json`) is deployed in resource group
+`is-ai-native-rg`. Data appears within ~1–3 minutes of a real visit.
+
+---
+
 
 The concrete chapter map is **designed by `playbook-architect`** from
 [`content/playbook-brief.md`](content/playbook-brief.md) and recorded in
 
@@ -0,0 +1,137 @@
+// Cookieless Azure Application Insights (RUM) for the gh-aw book.
+//
+// Uses the dependency-free BEACON transport from @webmaxru/cookieless-insights:
+// no cookies, no local/session storage, no persistent id -> no consent banner.
+// The connection string is a PUBLIC client key injected at build time by
+// site/generate.py as `window.__APPINSIGHTS_CONNECTION_STRING__` (empty in local
+// builds, so analytics is a no-op unless a key is present).
+//
+// Bundled to site/assets/analytics.js via `npm run build:analytics` (esbuild).
+
+import {
+  init,
+  trackEvent,
+  trackChangeDebounced,
+  getClient,
+} from '@webmaxru/cookieless-insights';
+
+// ─────────────────────────────────────────────────────────────────────────
+// KILL SWITCH: set to false to disable ALL telemetry (no beacon, no events).
+const ANALYTICS_ENABLED = true;
+// ─────────────────────────────────────────────────────────────────────────
+
+const connectionString =
+  (typeof window !== 'undefined' && window.__APPINSIGHTS_CONNECTION_STRING__) || '';
+
+// Safe no-op when disabled or when no connection string is present. Sends an
+// automatic page view on init (cookieless, in-memory session id per page load).
+init({
+  connectionString,
+  enabled: ANALYTICS_ENABLED,
+  cloudRole: 'gh-aw-book',
+});
+
+// Coarse, non-PII page context attached to every custom event.
+function context() {
+  const isHome = !!(document.body && document.body.classList.contains('home'));
+  return { page: isHome ? 'home' : 'chapter', path: location.pathname };
+}
+
+function langOf(codeEl) {
+  const cls = (codeEl && codeEl.className) || '';
+  const match = cls.match(/(?:language|lang)-([a-z0-9]+)/i);
+  return match ? match[1].toLowerCase() : 'text';
+}
+
+function trackLink(link) {
+  const href = link.getAttribute('href') || '';
+  if (!href || href.startsWith('javascript:')) return;
+
+  // In-page anchor: reader jumped to a section (TOC, "Contents", section links).
+  if (href.startsWith('#')) {
+    trackEvent('Section Navigated', { ...context(), hash: href.slice(0, 80) });
+    return;
+  }
+
+  let url;
+  try {
+    url = new URL(href, location.href);
+  } catch {
+    return;
+  }
+
+  if (url.origin !== location.origin) {
+    // Outbound: book repo, gh-aw, docs, author links, etc.
+    trackEvent('Outbound Link Clicked', { ...context(), host: url.host, href: url.href });
+    return;
+  }
+
+  // Same-origin navigation between book pages (chapter cards, pager, brand).
+  const label = (link.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  trackEvent('Internal Link Clicked', { ...context(), to: url.pathname + url.hash, label });
+}
+
+function onClick(event) {
+  const el = event.target instanceof Element ? event.target : null;
+  if (!el) return;
+
+  const themeBtn = el.closest('.theme-opt');
+  if (themeBtn) {
+    trackEvent('Theme Changed', { ...context(), theme: themeBtn.dataset.themeValue || 'unknown' });
+    return;
+  }
+
+  const sidebarBtn = el.closest('.sidebar-toggle');
+  if (sidebarBtn) {
+    // aria-expanded still holds the pre-toggle state at click time; invert it.
+    const willOpen = sidebarBtn.getAttribute('aria-expanded') !== 'true';
+    trackEvent('Chapter Sidebar Toggled', { ...context(), open: String(willOpen) });
+    return;
+  }
+
+  const copyBtn = el.closest('.copy-code');
+  if (copyBtn) {
+    const host = copyBtn.closest('figure.code, .code-block');
+    const codeEl = host ? host.querySelector('code') : null;
+    trackEvent('Code Copied', { ...context(), language: codeEl ? langOf(codeEl) : 'text' });
+    return;
+  }
+
+  const link = el.closest('a[href]');
+  if (link) trackLink(link);
+}
+
+// Debounced typing / slider drags. The site has no such inputs today; this
+// future-proofs any range slider, search box, or textarea by collapsing rapid
+// changes into a single event per control.
+function onInput(event) {
+  const el = event.target instanceof Element ? event.target : null;
+  if (!el) return;
+  const tag = el.tagName;
+  const type = (el.getAttribute && el.getAttribute('type')) || '';
+  const isTextInput =
+    tag === 'INPUT' && ['range', 'text', 'search', 'number', ''].includes(type);
+  if (isTextInput || tag === 'TEXTAREA' || el.getAttribute('contenteditable') === 'true') {
+    const key = el.id || el.getAttribute('name') || type || tag.toLowerCase();
+    trackChangeDebounced('Input Changed', String(key));
+  }
+}
+
+function wire() {
+  // "Opened via shared link": arrived on a deep link to a specific section.
+  if (location.hash && location.hash.length > 1) {
+    trackEvent('Opened Via Shared Link', { ...context(), hash: location.hash.slice(0, 80) });
+  }
+  // Capture phase so we still see events even if a handler stops propagation.
+  document.addEventListener('click', onClick, true);
+  document.addEventListener('input', onInput, true);
+}
+
+// Only attach listeners when telemetry is actually live (no-op otherwise).
+if (getClient() && getClient().enabled) {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', wire, { once: true });
+  } else {
+    wire();
+  }
+}