n-seo 0.1.1 → 0.3.0

package/docs/SETUP-GOOGLE.md

@@ -7,6 +7,13 @@ account with a JSON key** — a machine identity you add as a read-only user in
 each console. No gcloud install, no browser login, no token that expires when
 your session does.
 
+> **You can have this done for you.** `n-seo init` installed the
+> `n-seo-setup` skill in your instance. Open the directory in Claude Code and
+> say *"set this up for my sites"*: it works through everything below, runs
+> `n-seo doctor` between steps, and stops at each decision that is yours (the
+> Cloud project, the property ids, whether to grant access). This page is the
+> reference behind it, and what to read when something does not fit.
+
 ## 1. Pick a Google Cloud project
 
 Any project works; a dedicated one keeps it tidy. In the
@@ -120,7 +127,7 @@ Set `google.auth` to one of:
 
 | Mode | How it gets a token | When to use |
 |---|---|---|
-| `service-account-key` | Signs an OAuth JWT with the key file using `openssl` | Default. No extra tools |
+| `service-account-key` | Signs an OAuth JWT with the key file, using node's crypto module | Default. No extra tools, on any platform |
 | `gcloud-impersonate` | `gcloud auth print-access-token --impersonate-service-account=<google.impersonate>` | You already use gcloud and would rather grant your user *Service Account Token Creator* on the SA than keep a key file. Still add the SA to the consoles as above |
 | `gcloud-user` | `gcloud auth print-access-token` for your own login | Rarely works: gcloud's default client does not carry the Search Console or Analytics scopes for user credentials, and Google blocks `application-default login` with those scopes. Kept for completeness |
 | `metadata` | The runtime service account from the GCE / Cloud Run / GKE metadata server, exchanged for a scoped token | Running on Google Cloud. No key file exists, so none can leak |

package/ingest/analyze_ga4.py

@@ -24,7 +24,7 @@ def rows(site, name):
     p = GA_DIR / site / f"{name}.json"
     if not p.exists():
         return []
-    d = json.loads(p.read_text())
+    d = json.loads(p.read_text(encoding="utf-8"))
     out = []
     for r in d.get("rows", []):
         dims = [v["value"] for v in r.get("dimensionValues", [])]
@@ -69,7 +69,7 @@ def main():
     dest_dir = seo_config.INSTANCE / "docs" / "reports"
     dest_dir.mkdir(parents=True, exist_ok=True)
     dest = dest_dir / f"ga4-findings-{date.today():%Y-%m}.md"
-    dest.write_text(text)
+    dest.write_text(text, encoding="utf-8")
     print(text)
     print(f"[saved to {dest}]")
     return 0

package/ingest/analyze_gsc.py

@@ -19,7 +19,7 @@ EXPECTED_CTR = {1: 0.28, 2: 0.15, 3: 0.10, 4: 0.07, 5: 0.05, 6: 0.04}
 
 def load(slug, dataset):
     p = seo_config.DATA / "gsc" / slug / f"{dataset}.json"
-    return json.loads(p.read_text())["rows"] if p.exists() else []
+    return json.loads(p.read_text(encoding="utf-8"))["rows"] if p.exists() else []
 
 
 def fmt_pct(x):
@@ -126,7 +126,7 @@ def main():
     dest_dir = seo_config.INSTANCE / "docs" / "reports"
     dest_dir.mkdir(parents=True, exist_ok=True)
     dest = dest_dir / f"gsc-findings-{date.today():%Y-%m}.md"
-    dest.write_text(text)
+    dest.write_text(text, encoding="utf-8")
     print(text)
     print(f"\n[saved to {dest}]")
     return 0

package/ingest/analyze_metadata.py

@@ -73,7 +73,7 @@ def main():
         host = site["gscHost"]
         cache_key = str(gsc_file)
         if cache_key not in qp_cache:
-            qp_cache[cache_key] = json.loads(gsc_file.read_text())["rows"]
+            qp_cache[cache_key] = json.loads(gsc_file.read_text(encoding="utf-8"))["rows"]
         rows = [r for r in qp_cache[cache_key]
                 if r["keys"][1].split("/")[2] == host]
 
@@ -149,7 +149,7 @@ def main():
         print(f"{site['host']:28s} {len(pages)} pages audited, {len(findings)} with findings")
 
     seo_config.DATA.mkdir(parents=True, exist_ok=True)
-    (seo_config.DATA / "metadata-audit.json").write_text(json.dumps(audit, indent=1))
+    (seo_config.DATA / "metadata-audit.json").write_text(json.dumps(audit, indent=1), encoding="utf-8")
     print("saved data/metadata-audit.json")
     return 0
 

package/ingest/analyze_trends.py

@@ -93,7 +93,7 @@ def main():
         p = seo_config.DATA / "gsc" / slug / "dates.json"
         if p.exists():
             monthly = {}
-            for r in json.loads(p.read_text())["rows"]:
+            for r in json.loads(p.read_text(encoding="utf-8"))["rows"]:
                 m = r["keys"][0][:7]
                 cur = monthly.setdefault(m, {"clicks": 0, "imps": 0})
                 cur["clicks"] += r["clicks"]
@@ -122,7 +122,7 @@ def main():
 
     seo_config.DATA.mkdir(parents=True, exist_ok=True)
     dest = seo_config.DATA / f"trends-{date.today().isoformat()}.json"
-    dest.write_text(json.dumps(out, indent=1))
+    dest.write_text(json.dumps(out, indent=1), encoding="utf-8")
     print(f"saved {dest}\n")
 
     for site, d in out["sites"].items():

package/ingest/google_auth.py

@@ -3,10 +3,10 @@
   service-account-key (default, recommended)
       A service-account JSON key on disk (config google.serviceAccountKey,
       or $GOOGLE_APPLICATION_CREDENTIALS). We build the OAuth JWT ourselves
-      and sign it with the `openssl` CLI, so there is no gcloud and no pip
-      dependency. Add the service account's email to your Search Console
-      property (Full user) and your GA4 property (Viewer) — that is all the
-      access it gets.
+      and sign it with node's crypto module, so there is no gcloud, no pip
+      dependency and no openssl binary. Add the service account's email to
+      your Search Console property (Full user) and your GA4 property
+      (Viewer) — that is all the access it gets.
 
   gcloud-impersonate
       `gcloud auth print-access-token --impersonate-service-account=<sa>`.
@@ -33,9 +33,10 @@ inspection, analytics.readonly for GA4.
 import base64
 import json
 import os
+import shutil
 import subprocess
-import tempfile
 import time
+from pathlib import Path
 
 import seo_config
 from http_util import curl_json
@@ -58,6 +59,50 @@ def _b64url(b: bytes) -> str:
     return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
 
 
+# RS256 without an openssl binary. Node is already required (the dashboard
+# runs on it) and its crypto module produces byte-identical signatures, so
+# signing through node drops an external dependency on every platform — and
+# makes Windows work, where openssl is not installed by default.
+#
+# Key and payload go in over stdin, never on the command line: argv is
+# readable by any other process on the machine.
+_NODE_SIGN_JS = (
+    "let s='';"
+    "process.stdin.setEncoding('utf8')"
+    ".on('data', d => s += d)"
+    ".on('end', () => {"
+    "  const { key, data } = JSON.parse(s);"
+    "  const sig = require('node:crypto')"
+    "    .sign('sha256', Buffer.from(data, 'base64'), key);"
+    "  process.stdout.write(sig.toString('base64'));"
+    "});"
+)
+
+
+def node_bin() -> str:
+    """The node executable. $NODE overrides, mirroring $PYTHON for the CLI."""
+    return os.environ.get("NODE") or "node"
+
+
+def _sign_rs256(private_key_pem: str, data: bytes) -> bytes:
+    """RSASSA-PKCS1-v1_5 over SHA-256, the `RS256` a Google JWT needs."""
+    node = node_bin()
+    if not shutil.which(node):
+        raise RuntimeError(
+            f"{node} is not on PATH, and the service-account JWT is signed with it. "
+            "Install Node 20+ (it is required for the dashboard anyway), or set "
+            "$NODE to its path.")
+    payload = json.dumps({"key": private_key_pem,
+                          "data": base64.b64encode(data).decode()})
+    p = subprocess.run([node, "-e", _NODE_SIGN_JS],
+                       input=payload, capture_output=True, text=True)
+    if p.returncode != 0 or not p.stdout.strip():
+        raise RuntimeError(
+            "could not sign the service-account JWT — the key file's "
+            f"private_key may be malformed: {(p.stderr or '').strip()[:200]}")
+    return base64.b64decode(p.stdout.strip())
+
+
 def key_path() -> str | None:
     """The service-account key to sign with.
 
@@ -82,7 +127,7 @@ def _sa_key_token(scope: str) -> str:
         raise RuntimeError(
             "google.auth is service-account-key but no key file was found at "
             f"{kp or '(unset)'} — see docs/SETUP-GOOGLE.md")
-    key = json.loads(open(kp).read())
+    key = json.loads(Path(kp).read_text(encoding="utf-8"))
     # Backdate slightly: Google rejects a JWT issued in its future, so a
     # machine whose clock runs a few seconds fast otherwise fails to
     # authenticate at all, with an error that names nothing useful.
@@ -93,19 +138,7 @@ def _sa_key_token(scope: str) -> str:
         "iat": iat, "exp": iat + 3600,
     }).encode())
     signing_input = f"{header}.{claims}".encode()
-    # openssl needs the private key in a file; keep it 0600 and short-lived.
-    fd, tmp = tempfile.mkstemp(prefix="n-seo-", suffix=".pem")
-    try:
-        os.fchmod(fd, 0o600)
-        with os.fdopen(fd, "w") as f:
-            f.write(key["private_key"])
-        sig = subprocess.run(["openssl", "dgst", "-sha256", "-sign", tmp],
-                             input=signing_input, capture_output=True, check=True).stdout
-    finally:
-        try:
-            os.unlink(tmp)
-        except OSError:
-            pass
+    sig = _sign_rs256(key["private_key"], signing_input)
     assertion = signing_input.decode() + "." + _b64url(sig)
     resp = curl_json([
         "-X", "POST", "-d", f"grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={assertion}",
@@ -222,7 +255,7 @@ def service_account_email() -> str | None:
     kp = key_path()
     if kp and os.path.exists(kp):
         try:
-            return json.loads(open(kp).read()).get("client_email")
+            return json.loads(Path(kp).read_text(encoding="utf-8")).get("client_email")
         except (OSError, json.JSONDecodeError):
             return None
     return None

package/ingest/pull_ga4.py

@@ -96,7 +96,7 @@ def main():
                 continue
             (site_dir / f"{name}.json").write_text(json.dumps(
                 {"site": host, "property": f"properties/{prop}",
-                 "pulled": date.today().isoformat(), **resp}))
+                 "pulled": date.today().isoformat(), **resp}), encoding="utf-8")
             print(f"{host:28s} {name:8s} {resp.get('rowCount', 0)} rows")
 
     print(f"\nSaved under {out_root}")

package/ingest/pull_gsc.py

@@ -100,7 +100,7 @@ def main():
                     "rowCount": len(result["rows"]),
                     "rows": result["rows"],
                 }
-                (site_dir / f"{name}{suffix}.json").write_text(json.dumps(payload))
+                (site_dir / f"{name}{suffix}.json").write_text(json.dumps(payload), encoding="utf-8")
                 print(f"{slug:28s} {name}{suffix:5s} {len(result['rows'])} rows")
 
     print(f"\nWindows: {start_full} and {start_recent} -> {end}\nSaved under {out_root}")

package/ingest/pull_index_status.py

@@ -170,7 +170,7 @@ def main() -> int:
               f"({len(never_crawled)} never crawled)")
 
     OUT.parent.mkdir(parents=True, exist_ok=True)
-    OUT.write_text(json.dumps(out, indent=2))
+    OUT.write_text(json.dumps(out, indent=2), encoding="utf-8")
     print(f"saved {OUT} — {total_problems} URLs needing attention")
     return 0
 

package/ingest/pull_timeseries.py

@@ -87,7 +87,7 @@ def main():
             if failed:
                 continue
             (OUT / f"gsc-{slug}.json").write_text(json.dumps(
-                {"site": site, "startDate": start, "endDate": end, "rows": rows}))
+                {"site": site, "startDate": start, "endDate": end, "rows": rows}), encoding="utf-8")
             print(f"gsc  {slug:28s} {len(rows)} date x page rows")
 
     ga4_props = seo_config.ga4_properties()
@@ -104,7 +104,7 @@ def main():
                          "page": row["dimensionValues"][1]["value"],
                          "sessions": float(row["metricValues"][0]["value"])}
                         for row in batch]
-                (OUT / f"ga4-{host}.json").write_text(json.dumps({"site": host, "rows": rows}))
+                (OUT / f"ga4-{host}.json").write_text(json.dumps({"site": host, "rows": rows}), encoding="utf-8")
                 print(f"ga4  {host:28s} {len(rows)} date x page rows")
 
             batch, ok = ga4_series(tok, prop, ["date", "sessionSource", "sessionMedium"],
@@ -118,7 +118,7 @@ def main():
                          "sessions": float(row["metricValues"][0]["value"])}
                         for row in batch]
                 (OUT / f"ga4-sources-{host}.json").write_text(
-                    json.dumps({"site": host, "rows": rows}))
+                    json.dumps({"site": host, "rows": rows}), encoding="utf-8")
                 print(f"ga4  {host:28s} {len(rows)} date x source rows")
 
     if not gsc_props and not ga4_props:

package/ingest/seo_config.py

@@ -9,8 +9,24 @@ and export. Stdlib only.
 import json
 import os
 import subprocess
+import sys
 from pathlib import Path
 
+# Print UTF-8 whatever the platform thinks the console encoding is.
+#
+# Windows picks the ANSI code page (cp1252 on a US install) for a piped
+# stdout, so the em dashes and middle dots this tool prints come out as
+# mojibake or raise UnicodeEncodeError mid-run. Every entry point imports
+# this module, so fixing it once here covers all of them. File I/O is
+# handled separately: every read_text/write_text/open call passes
+# encoding="utf-8" explicitly, and tests/py/test_portability.py enforces it.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        if getattr(_stream, "encoding", "").lower().replace("-", "") != "utf8":
+            _stream.reconfigure(encoding="utf-8")
+    except (AttributeError, ValueError, OSError):
+        pass  # a captured or replaced stream; nothing to fix
+
 # The engine checkout: code, engine docs, public assets.
 ROOT = Path(__file__).resolve().parent.parent
 # The instance: one user's config, queue, content and data. Defaults to the
@@ -50,7 +66,7 @@ def load(force: bool = False) -> dict:
     if _cache is not None and not force:
         return _cache
     path = CONFIG_PATH if CONFIG_PATH.exists() else EXAMPLE_PATH
-    raw = json.loads(path.read_text())
+    raw = json.loads(path.read_text(encoding="utf-8"))
     modules = {k: {"enabled": False, **MODULE_DEFAULTS.get(k, {})} for k in MODULE_KEYS}
     for k, v in (raw.get("modules") or {}).items():
         modules[k] = {"enabled": False, **MODULE_DEFAULTS.get(k, {}), **(v or {})}
@@ -96,7 +112,7 @@ def load(force: bool = False) -> dict:
 def engine_info() -> dict:
     """Mirrors src/config.ts engineInfo(): what engine is running, for which instance."""
     try:
-        version = json.loads((ROOT / "package.json").read_text()).get("version", "0.0.0")
+        version = json.loads((ROOT / "package.json").read_text(encoding="utf-8")).get("version", "0.0.0")
     except (OSError, json.JSONDecodeError):
         version = "0.0.0"
     try:
@@ -204,7 +220,7 @@ def env(key: str, default: str = "") -> str:
     if os.environ.get(key):
         return os.environ[key]
     try:
-        for line in (INSTANCE / ".env").read_text().splitlines():
+        for line in (INSTANCE / ".env").read_text(encoding="utf-8").splitlines():
             line = line.strip()
             if line.startswith(f"{key}="):
                 return line.split("=", 1)[1].strip().strip('"').strip("'")

package/ops/daily.py

@@ -57,7 +57,7 @@ STEPS = [
 def log(line: str):
     print(line, flush=True)
     LOG.parent.mkdir(parents=True, exist_ok=True)
-    with LOG.open("a") as f:
+    with LOG.open("a", encoding="utf-8") as f:
         f.write(line.rstrip("\n") + "\n")
 
 
@@ -230,7 +230,7 @@ def main():
             "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%MZ"),
             "failures": "; ".join(failures),
             "steps": results,
-        }, indent=1))
+        }, indent=1), encoding="utf-8")
 
     write_last_run()
     if run_hooks_flag and hooks["afterRun"]:

package/ops/daily_diff.py

@@ -31,7 +31,7 @@ PROBE_KEYS = [
 
 def probes():
     files = sorted((DATA / "probes").glob("probe-*.json"))
-    return [json.loads(f.read_text()) for f in files[-2:]]
+    return [json.loads(f.read_text(encoding="utf-8")) for f in files[-2:]]
 
 
 def watch_groups():
@@ -76,7 +76,7 @@ def main():
         if not f.exists():
             continue
         win = "90d" if f90.exists() else "16mo"
-        by_url = {r["keys"][0]: r for r in json.loads(f.read_text())["rows"]}
+        by_url = {r["keys"][0]: r for r in json.loads(f.read_text(encoding="utf-8"))["rows"]}
         for url in urls:
             r = by_url.get(url) or by_url.get(url.rstrip("/")) or by_url.get(url + "/")
             label = url.split("//", 1)[-1]
@@ -90,7 +90,7 @@ def main():
     conv = seo_config.load()["conversions"]
     if conv:
         try:
-            fr = json.loads((DATA / "ga4" / conv["site"] / "funnel.json").read_text())
+            fr = json.loads((DATA / "ga4" / conv["site"] / "funnel.json").read_text(encoding="utf-8"))
             rows = fr.get("rows", [])
             if rows:
                 counts = {}
@@ -113,7 +113,7 @@ def main():
         # subdomain's own traffic as a referral from the apex
         others = {h.removeprefix("www.") for h in hosts if h != host}
         xref = []
-        for r in json.loads(p.read_text()).get("rows", []):
+        for r in json.loads(p.read_text(encoding="utf-8")).get("rows", []):
             name = r["dimensionValues"][0]["value"]
             if name.lower().removeprefix("www.") in others:
                 xref.append(f"{name}={float(r['metricValues'][0]['value']):.0f}")
@@ -123,7 +123,8 @@ def main():
     log = INSTANCE / "docs" / "daily-log.md"
     log.parent.mkdir(parents=True, exist_ok=True)
     if not log.exists():
-        log.write_text("# Daily ops log\n\nAppended by ops/daily.py — newest entries last.\n")
+        log.write_text("# Daily ops log\n\nAppended by ops/daily.py — newest entries last.\n",
+                       encoding="utf-8")
     today = date.today().isoformat()
     entry = [f"\n## {today}\n"]
     entry += [f"- **ALERT:** {a}" for a in alerts]
@@ -132,15 +133,15 @@ def main():
 
     # Re-running on the same day must replace today's entry, not stack a
     # second one under the same heading.
-    text = log.read_text()
+    text = log.read_text(encoding="utf-8")
     head = f"\n## {today}\n"
     start = text.find(head)
     if start == -1:
-        log.write_text(text.rstrip("\n") + "\n" + body)
+        log.write_text(text.rstrip("\n") + "\n" + body, encoding="utf-8")
     else:
         nxt = text.find("\n## ", start + len(head))
         tail = text[nxt:] if nxt != -1 else ""
-        log.write_text(text[:start].rstrip("\n") + "\n" + body + tail.lstrip("\n"))
+        log.write_text(text[:start].rstrip("\n") + "\n" + body + tail.lstrip("\n"), encoding="utf-8")
     for a in alerts:
         print(f"ALERT: {a}")
     print(f"daily-log updated ({len(alerts)} alerts, {len(lines)} lines)")

package/ops/demo_data.py

@@ -151,7 +151,7 @@ def write_gsc(prop, slug, sites_in_prop, index_of):
                                   ("queries", ["query"], agg(by_q)),
                                   ("pages", ["page"], agg(by_p))):
             (d / f"{name}{suffix}.json").write_text(json.dumps(
-                {**meta, "dimensions": dims, "rowCount": len(rows_), "rows": rows_}))
+                {**meta, "dimensions": dims, "rowCount": len(rows_), "rows": rows_}), encoding="utf-8")
 
     dataset(full_rows, 1.0, "", END - timedelta(days=FULL_DAYS))
     dataset(full_rows, 0.22, "_90d", END - timedelta(days=RECENT_DAYS))
@@ -168,7 +168,7 @@ def write_gsc(prop, slug, sites_in_prop, index_of):
                       "ctr": clicks / imps if imps else 0, "position": round(rng.uniform(9, 14), 1)})
     (d / "dates.json").write_text(json.dumps(
         {"site": prop, "dimensions": ["date"], "startDate": day0.isoformat(), "endDate": END.isoformat(),
-         "rowCount": len(dates), "rows": dates}))
+         "rowCount": len(dates), "rows": dates}), encoding="utf-8")
     return full_rows
 
 
@@ -199,14 +199,14 @@ def write_ga4(site, idx, conv, gsc_rows):
     total = sum(m[0] for _, m in daily)
     meta = {"site": host, "property": f"properties/{site.get('ga4Property') or '000000000'}",
             "pulled": TODAY.isoformat()}
-    (d / "daily.json").write_text(json.dumps({**meta, **ga4_report(["date"], ["sessions", "totalUsers"], daily)}))
+    (d / "daily.json").write_text(json.dumps({**meta, **ga4_report(["date"], ["sessions", "totalUsers"], daily)}), encoding="utf-8")
 
     mix = [(src, med, w) for src, med, w, _ai in SOURCE_MIX]
     others = [h for h in seo_config.hosts() if h != host]
     if others:
         mix.append((others[0], "referral", 0.015))
     sources = [([src, med], [round(total * w), round(total * w * 0.8)]) for src, med, w in mix]
-    (d / "sources.json").write_text(json.dumps({**meta, **ga4_report(["sessionSource", "sessionMedium"], ["sessions", "totalUsers"], sources)}))
+    (d / "sources.json").write_text(json.dumps({**meta, **ga4_report(["sessionSource", "sessionMedium"], ["sessions", "totalUsers"], sources)}), encoding="utf-8")
 
     pages = sorted({r[1] for r in gsc_rows if r[1].split("/")[2] == site["gscHost"]})
     paths = [p.split(site["gscHost"], 1)[1].rstrip("/") or "/" for p in pages] or ["/", "/docs", "/pricing"]
@@ -219,7 +219,7 @@ def write_ga4(site, idx, conv, gsc_rows):
             eng = 0.18
         landing.append(([p], [sessions, round(eng, 4)]))
     landing.sort(key=lambda r: -r[1][0])
-    (d / "landing.json").write_text(json.dumps({**meta, **ga4_report(["landingPage"], ["sessions", "engagementRate"], landing)}))
+    (d / "landing.json").write_text(json.dumps({**meta, **ga4_report(["landingPage"], ["sessions", "engagementRate"], landing)}), encoding="utf-8")
 
     if conv and conv.get("site") == host:
         rows = []
@@ -227,7 +227,7 @@ def write_ga4(site, idx, conv, gsc_rows):
             day = (day0 + timedelta(days=i)).strftime("%Y%m%d")
             for ev in conv.get("events", [])[:2]:
                 rows.append(([day, ev, rng.choice(["web", "docs", "(not set)"])], [rng.randint(0, 4)]))
-        (d / "funnel.json").write_text(json.dumps({**meta, **ga4_report(["date", "eventName", conv.get("sourceDimension") or "customEvent:source_app"], ["eventCount"], rows)}))
+        (d / "funnel.json").write_text(json.dumps({**meta, **ga4_report(["date", "eventName", conv.get("sourceDimension") or "customEvent:source_app"], ["eventCount"], rows)}), encoding="utf-8")
     return paths, total
 
 
@@ -250,7 +250,7 @@ def write_timeseries(prop, slug, sites_in_prop, gsc_rows, ga4_paths):
                 rows.append({"keys": [day.isoformat(), p], "clicks": round(dc), "impressions": round(di),
                              "ctr": (dc / di) if di else 0, "position": round(rng.uniform(4, 20), 1)})
     (d / f"gsc-{slug}.json").write_text(json.dumps(
-        {"site": prop, "startDate": day0.isoformat(), "endDate": END.isoformat(), "rows": rows}))
+        {"site": prop, "startDate": day0.isoformat(), "endDate": END.isoformat(), "rows": rows}), encoding="utf-8")
     for s in sites_in_prop:
         paths, total = ga4_paths.get(s["host"], ([], 0))
         if not s.get("ga4Property"):
@@ -263,7 +263,7 @@ def write_timeseries(prop, slug, sites_in_prop, gsc_rows, ga4_paths):
                 v = weekly(day, (total / 90) * (0.35 if j == 0 else 0.08), day0=ga0)
                 if round(v):
                     rows.append({"date": day.strftime("%Y%m%d"), "page": p, "sessions": round(v)})
-        (d / f"ga4-{s['host']}.json").write_text(json.dumps({"site": s["host"], "rows": rows}))
+        (d / f"ga4-{s['host']}.json").write_text(json.dumps({"site": s["host"], "rows": rows}), encoding="utf-8")
 
         # date x source/medium. AI assistants grow over the window and the
         # rest hold roughly flat, so the demo actually shows the thing the
@@ -278,7 +278,7 @@ def write_timeseries(prop, slug, sites_in_prop, gsc_rows, ga4_paths):
                     rows.append({"date": day.strftime("%Y%m%d"), "source": src,
                                  "medium": med, "sessions": round(v)})
         (d / f"ga4-sources-{s['host']}.json").write_text(
-            json.dumps({"site": s["host"], "rows": rows}))
+            json.dumps({"site": s["host"], "rows": rows}), encoding="utf-8")
 
 
 def write_probe(sites):
@@ -302,7 +302,7 @@ def write_probe(sites):
             "soft_404": {"status": 404, "real_404": True},
         })
     now = datetime.now(timezone.utc)
-    (d / f"probe-{now:%Y%m%d-%H%M%S}.json").write_text(json.dumps({"probed_at": now.isoformat(), "sites": out}, indent=2))
+    (d / f"probe-{now:%Y%m%d-%H%M%S}.json").write_text(json.dumps({"probed_at": now.isoformat(), "sites": out}, indent=2), encoding="utf-8")
 
 
 def write_metadata_audit(sites, gsc_by_host):
@@ -333,7 +333,7 @@ def write_metadata_audit(sites, gsc_by_host):
                              "imps": imps, "clicks": sum(q["clicks"] for q in qs), "issues": issues,
                              "top_queries": qs[:5], "missed_clicks_window": missed})
         audit["sites"][s["host"]] = findings
-    (DATA / "metadata-audit.json").write_text(json.dumps(audit, indent=1))
+    (DATA / "metadata-audit.json").write_text(json.dumps(audit, indent=1), encoding="utf-8")
 
 
 def write_index_status(sites, gsc_by_host):
@@ -365,7 +365,7 @@ def write_index_status(sites, gsc_by_host):
                                                     "pending": False, "errors": 0, "warnings": 0}]},
             "problems": problems,
         }
-    (DATA / "index-status.json").write_text(json.dumps(out, indent=2))
+    (DATA / "index-status.json").write_text(json.dumps(out, indent=2), encoding="utf-8")
 
 
 def write_trends(props, sites, gsc_rows_by_prop):
@@ -399,7 +399,7 @@ def write_trends(props, sites, gsc_rows_by_prop):
 
         monthly = {}
         dates_file = DATA / "gsc" / slug / "dates.json"
-        for r in json.loads(dates_file.read_text())["rows"]:
+        for r in json.loads(dates_file.read_text(encoding="utf-8"))["rows"]:
             m = r["keys"][0][:7]
             cur = monthly.setdefault(m, {"clicks": 0, "imps": 0})
             cur["clicks"] += r["clicks"]
@@ -417,7 +417,7 @@ def write_trends(props, sites, gsc_rows_by_prop):
             total[ym] = t
             ai[ym] = round(t * (0.01 + (12 - k) * 0.004))
         out["ai_referrals"][s["host"]] = {"ai": ai, "total": total}
-    (DATA / f"trends-{TODAY.isoformat()}.json").write_text(json.dumps(out, indent=1))
+    (DATA / f"trends-{TODAY.isoformat()}.json").write_text(json.dumps(out, indent=1), encoding="utf-8")
 
 
 def write_proposals(sites, gsc_by_host):
@@ -450,7 +450,7 @@ def write_proposals(sites, gsc_by_host):
                       "evidence": "DEMO DATA — 12 days since the change; CTR up from 1.9% to 2.6% but the 28-day window has not closed."}],
         "inference_ran": True,
     }
-    (DATA / "opportunity-proposals.json").write_text(json.dumps(out, indent=1))
+    (DATA / "opportunity-proposals.json").write_text(json.dumps(out, indent=1), encoding="utf-8")
 
 
 def write_run_files():
@@ -459,8 +459,8 @@ def write_run_files():
         "ts": ts.strftime("%Y-%m-%dT%H:%MZ"), "failures": "",
         "steps": [{"name": n, "ok": True, "seconds": s} for n, s in
                   (("probe", 6.2), ("gsc", 41.0), ("ga4", 9.8), ("timeseries", 22.4), ("metadata-audit", 14.1),
-                   ("index-status", 38.5), ("opportunity-scan", 17.0), ("daily-diff", 0.3))]}, indent=1))
-    with (DATA / "daily-ops.log").open("a") as f:
+                   ("index-status", 38.5), ("opportunity-scan", 17.0), ("daily-diff", 0.3))]}, indent=1), encoding="utf-8")
+    with (DATA / "daily-ops.log").open("a", encoding="utf-8") as f:
         f.write(f"=== daily run {ts:%Y-%m-%d %H:%M} (demo data) ===\n")
         f.write("--- probe\n  2 sites probed\n--- gsc\n  2 properties pulled\n--- daily-diff\n  daily-log updated (0 alerts)\n")
         f.write("=== done (0 failures) ===\n")
@@ -522,6 +522,12 @@ def main():
     else:
         print("\nnow run: n-seo start   (then open the dashboard)")
         print("remove with: n-seo demo --clean")
+    # The demo answers "what is this"; the next question is always "how do I
+    # point it at my own sites", and the answer is a sentence, not a doc.
+    if (seo_config.INSTANCE / ".claude" / "skills" / "n-seo-setup" / "SKILL.md").exists():
+        print("\nwhen you want it on your own sites, you can just ask:")
+        print(f"  cd {seo_config.INSTANCE} && claude")
+        print('  "set this up for my sites"   → /n-seo-setup')
     return 0