n-seo 0.1.1 → 0.2.0

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")

package/ops/doctor.py

@@ -64,10 +64,19 @@ def check_config():
 
 def check_tools():
     print("tools")
-    for tool, why in (("curl", "all HTTP goes through curl"), ("openssl", "signs the service-account JWT")):
-        report("OK" if shutil.which(tool) else "FAIL", tool, "" if shutil.which(tool) else f"install it — {why}")
+    report("OK" if shutil.which("curl") else "FAIL", "curl",
+           "" if shutil.which("curl") else "install it — all HTTP goes through curl "
+           "(Windows 10+ ships it in System32)")
+    # node signs the service-account JWT, so it is required even for someone
+    # who never opens the dashboard.
+    import google_auth
+    node = google_auth.node_bin()
+    report("OK" if shutil.which(node) else "FAIL", f"node ({node})",
+           "" if shutil.which(node) else "install Node 20+ — it runs the dashboard "
+           "and signs the service-account JWT; $NODE overrides the path")
     v = sys.version_info
-    report("OK" if v >= (3, 10) else "FAIL", f"python {v.major}.{v.minor}",
+    report("OK" if v >= (3, 10) else "FAIL",
+           f"python {v.major}.{v.minor} ({Path(sys.executable).name})",
            "" if v >= (3, 10) else "3.10+ required")
     nm = seo_config.ROOT / "node_modules"
     report("OK" if nm.exists() else "WARN", "node_modules", "" if nm.exists() else "run: npm install")
@@ -86,7 +95,7 @@ def check_auth(cfg):
                    f"{kp or '(unset)'} — set google.serviceAccountKey or $GOOGLE_APPLICATION_CREDENTIALS; see docs/SETUP-GOOGLE.md")
             return None
         try:
-            key = json.loads(Path(kp).read_text())
+            key = json.loads(Path(kp).read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError) as exc:
             report("FAIL", "key file unreadable", str(exc))
             return None
@@ -197,7 +206,6 @@ def check_modules(cfg):
     report("OK", "enabled: " + (", ".join(on) or "(none beyond defaults)"))
     llm = cfg["modules"].get("llm", {})
     if llm.get("enabled"):
-        import shlex
         sys.path.insert(0, str(Path(__file__).resolve().parent))
         import llm as llm_mod
         http = llm_mod.http_config()
@@ -211,11 +219,17 @@ def check_modules(cfg):
                    f"check provider/model and that {llm['http'].get('apiKeyEnv') or 'apiKeyEnv'} "
                    "is set in the environment or .env")
         for key in ("command", "fastCommand"):
-            cmd = shlex.split(str(llm.get(key) or ""))
+            raw = str(llm.get(key) or "").strip()
+            cmd = llm_mod.split_command(raw)
             if not cmd:
+                if raw:
+                    # Configured but unparseable — almost always an unbalanced
+                    # quote. Say so, or the next line reads as "not configured".
+                    report("FAIL", f"llm.{key} could not be parsed: {raw[:60]}",
+                           "check for an unbalanced quote")
                 # Only complain about a missing command when there is no http
                 # block at all; a broken one already reported itself.
-                if key == "command" and not http and not llm.get("http"):
+                elif key == "command" and not http and not llm.get("http"):
                     report("FAIL", "llm has neither http nor command configured")
                 continue
             report("OK" if shutil.which(cmd[0]) else "FAIL", f"llm.{key}: {cmd[0]}",

package/ops/export_static.py

@@ -103,11 +103,11 @@ def main():
             html = html.replace("</body>", staleness + "</body>", 1)
             dest = out / "index.html" if route == "/" else out / route.lstrip("/") / "index.html"
             dest.parent.mkdir(parents=True, exist_ok=True)
-            dest.write_text(html)
+            dest.write_text(html, encoding="utf-8")
 
-        (out / "styles.css").write_text(fetch("/styles.css"))
-        (out / "favicon.svg").write_text(fetch("/favicon.svg"))
-        (out / "robots.txt").write_text("User-agent: *\nDisallow: /\n")
+        (out / "styles.css").write_text(fetch("/styles.css"), encoding="utf-8")
+        (out / "favicon.svg").write_text(fetch("/favicon.svg"), encoding="utf-8")
+        (out / "robots.txt").write_text("User-agent: *\nDisallow: /\n", encoding="utf-8")
     except BaseException:
         # Never leave a half-built staging directory behind; the next
         # run would otherwise start from someone else's leftovers.

package/ops/hn_digest.py

@@ -157,7 +157,7 @@ def main():
     seo_config.DATA.mkdir(parents=True, exist_ok=True)
     (seo_config.DATA / "hn-digest.json").write_text(json.dumps(
         {"generated": datetime.now(timezone.utc).isoformat(timespec="minutes"),
-         "stats": stats, "picks": picks}, indent=1))
+         "stats": stats, "picks": picks}, indent=1), encoding="utf-8")
     for p in picks:
         print(f"- {p['title']} ({p['comments']}c/{p['points']}p) {p['url']}  [{p['why']}]")
     if not picks:

package/ops/indexnow.py

@@ -33,12 +33,12 @@ def key_file() -> Path:
 def cmd_init() -> int:
     kf = key_file()
     if kf.exists():
-        key = kf.read_text().strip()
+        key = kf.read_text(encoding="utf-8").strip()
         print(f"key file already exists: {kf}")
     else:
         key = secrets.token_hex(16)
         kf.parent.mkdir(parents=True, exist_ok=True)
-        kf.write_text(key + "\n")
+        kf.write_text(key + "\n", encoding="utf-8")
         print(f"wrote {kf}")
     print(f"\nkey: {key}\n\nServe this key as plain text at, for every site:")
     for s in seo_config.sites():
@@ -52,7 +52,7 @@ def cmd_ping(urls: list[str]) -> int:
     if not kf.exists():
         print(f"no key file at {kf} — run: python3 ops/indexnow.py init")
         return 1
-    key = kf.read_text().strip()
+    key = kf.read_text(encoding="utf-8").strip()
     by_host: dict[str, list[str]] = {}
     for u in urls:
         host = urlsplit(u).netloc

package/ops/llm.py

@@ -28,6 +28,7 @@ path runs. Nothing that comes back is applied automatically: callers turn
 replies into briefings or proposals a human accepts or ignores.
 """
 import json
+import os
 import shlex
 import shutil
 import subprocess
@@ -42,6 +43,27 @@ ANTHROPIC_VERSION = "2023-06-01"
 MAX_TOKENS = 4096
 
 
+def split_command(cmd: str) -> list[str]:
+    """Split a configured command string into argv, per platform.
+
+    POSIX rules treat a backslash as an escape, so on Windows they quietly
+    turn `C:\\tools\\claude.exe` into `C:toolsclaude.exe`. There, split with
+    the non-POSIX rules cmd.exe uses and strip the quotes shlex leaves on.
+
+    Returns [] for anything unparseable. This string comes from the Settings
+    form, so a stray quote is a typo a user can make, and it must not take
+    the daily run down with a ValueError from inside shlex — callers already
+    treat [] as "no command configured". doctor tells them which it was.
+    """
+    try:
+        if os.name != "nt":
+            return shlex.split(cmd)
+        parts = shlex.split(cmd, posix=False)
+    except ValueError:
+        return []
+    return [p[1:-1] if len(p) > 1 and p[0] == p[-1] == '"' else p for p in parts]
+
+
 def _enabled() -> dict | None:
     m = seo_config.module("llm")
     return m if m.get("enabled") else None
@@ -71,7 +93,7 @@ def command(fast: bool = False) -> list[str] | None:
     if not m:
         return None
     cmd = (m.get("fastCommand") if fast else None) or m.get("command") or ""
-    parts = shlex.split(str(cmd))
+    parts = split_command(str(cmd))
     if not parts or not shutil.which(parts[0]):
         return None
     return parts

package/ops/opportunity_scan.py

@@ -36,7 +36,7 @@ RISE_MIN_RATIO = 2.5     # and have grown at least this much vs prior 84d
 
 def latest_trends():
     files = sorted(DATA.glob("trends-*.json"))
-    return json.loads(files[-1].read_text()) if files else None
+    return json.loads(files[-1].read_text(encoding="utf-8")) if files else None
 
 
 def queue():
@@ -51,7 +51,7 @@ def queue():
     except json.JSONDecodeError:
         pass
     try:
-        return json.loads((seo_config.INSTANCE / "config" / "backlog.json").read_text()).get("actions", [])
+        return json.loads((seo_config.INSTANCE / "config" / "backlog.json").read_text(encoding="utf-8")).get("actions", [])
     except (OSError, json.JSONDecodeError):
         return []
 
@@ -84,7 +84,7 @@ def _host_resolver(prop):
     best = {}
     qp = seo_config.DATA / "gsc" / seo_config.gsc_data_slug(prop) / "query_page_90d.json"
     try:
-        for r in json.loads(qp.read_text()).get("rows", []):
+        for r in json.loads(qp.read_text(encoding="utf-8")).get("rows", []):
             q, page = r["keys"][0], r["keys"][1]
             h = page.split("/")[2] if page.count("/") >= 2 else ""
             if h in by_gsc_host and r["impressions"] > best.get(q, (0, ""))[0]:
@@ -175,7 +175,7 @@ def main():
         print("llm module off — candidates recorded without proposals")
 
     DATA.mkdir(parents=True, exist_ok=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")
     print(f"candidates: {len(candidates)} | proposals: {len(out['proposals'])} | "
           f"verdicts: {len(out['verdicts'])} | inference: {out['inference_ran']}")
     return 0

package/ops/py.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/* Run a Python script with whichever interpreter this machine actually has.
+ *
+ * The npm scripts used to hardcode `python3`, which does not exist on
+ * Windows: Python installs there as `python`, or only behind the `py`
+ * launcher. Worse, Windows ships an App Execution Alias at `python3.exe`
+ * that opens the Microsoft Store instead of running anything, so a hardcoded
+ * `python3` fails in a way that looks like Python is missing when it is not.
+ * Probing for one that answers `--version` is the only reliable answer.
+ *
+ *   node ops/py.mjs ops/doctor.py --offline
+ *
+ * $PYTHON overrides, which is also how the n-seo CLI behaves.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const CANDIDATES = process.platform === "win32"
+  ? ["python", "python3", "py"]
+  : ["python3", "python"];
+
+export function pythonBin() {
+  if (process.env.PYTHON) return process.env.PYTHON;
+  for (const c of CANDIDATES) {
+    const probe = spawnSync(c, ["--version"], { stdio: "ignore" });
+    if (!probe.error && probe.status === 0) return c;
+  }
+  return CANDIDATES[0]; // let the real command fail with a useful message
+}
+
+// Only act as a launcher when invoked directly, not when imported.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const child = spawn(pythonBin(), process.argv.slice(2), { stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(`could not start ${pythonBin()}: ${err.message}`);
+    console.error("install Python 3.10+, or set $PYTHON to its path");
+    process.exit(127);
+  });
+  child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 1));
+}

package/ops/reddit_digest.py

@@ -151,7 +151,7 @@ def main():
     seo_config.DATA.mkdir(parents=True, exist_ok=True)
     (seo_config.DATA / "reddit-digest.json").write_text(json.dumps(
         {"generated": datetime.now(timezone.utc).isoformat(timespec="minutes"),
-         "user": user or None, "auth": bool(oauth_token()), "picks": picks}, indent=1))
+         "user": user or None, "auth": bool(oauth_token()), "picks": picks}, indent=1), encoding="utf-8")
     for p in picks:
         print(f"- r/{p['sub']}: {p['title']} ({p['comments']}c/{p['score']}pts, {p['age_days']}d) {p['url']}")
     if not picks: