docs/preferred-sources.md

@@ -0,0 +1,34 @@
+# Google Preferred Sources — status & future to-do
+
+**What it is:** Google's "Preferred Sources" lets readers mark MSOS as a
+favourite so we surface more in Top Stories / Discover / News / AI surfaces.
+Implemented in `preferred-source.js` (loaded site-wide via `tools/seo_inject.py`
+`GA_LINES`).
+
+## Current state (set 2026-08-30)
+- ✅ **Footer link** ("Add us on Google") is LIVE on every page — a subtle text
+  link in `.legal-links`, using the domain deeplink
+  `https://www.google.com/preferences/source?q=msosorg.com`.
+- ⏸️ **Hub pill button is DISABLED** — `addPill()` is commented out in
+  `preferred-source.js` (`init()` only calls `addFooterLink()`).
+
+## Why the pill is disabled
+`msosorg.com` is **not yet a Google "Top Stories" source**, so the tool returns
+**"No results"** and the button dead-ends. Eligibility requirement (confirmed
+via Google Search Central): the site must already appear in **Top Stories** for
+readers to add it as a preferred source.
+
+## ▶️ FUTURE TO-DO — re-enable the pill once eligible
+1. Check eligibility: search 3–4 of our news topics on Google; if `msosorg.com`
+   appears in a **Top Stories** box, we're eligible.
+2. To get there: publish timely, original news regularly; keep pages indexed;
+   add/maintain the publication in **Google Publisher Center**
+   (publishercenter.google.com).
+3. Re-enable: in `preferred-source.js`, restore `addPill();` in `init()`
+   (uncomment it). Pill renders on homepage / News hub / Blog hub, under the H1.
+4. Verify the deeplink now returns MSOS (no longer "No results").
+
+## Related (also shipped 2026-08-30)
+- Cookie banner: benefit-led copy + **analytics-only** consent (`consent.js`).
+- **Cloudflare Web Analytics** (cookieless, counts everyone) via `seo_inject.py`.
+- Events structured data: `endDate`/`performer`/`offers` in `event_schema()`.

preferred-source.js

@@ -58,7 +58,12 @@
     document.head.appendChild(s);
   }
 
-  function init() { addFooterLink(); addPill(); }
+  // NOTE (future to-do): the interactive hub pill (addPill) is intentionally
+  // DISABLED for now. msosorg.com is not yet a Google "Top Stories" source, so
+  // the button dead-ends at "No results". Re-enable addPill() once the site
+  // appears in Top Stories (see docs/preferred-sources.md). The subtle footer
+  // link stays on, ready for when eligibility kicks in.
+  function init() { addFooterLink(); /* addPill(); disabled until Top Stories eligible */ }
   if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init);
   else init();
 })();