n-seo 0.1.1 → 0.3.0

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]}",
@@ -259,6 +273,15 @@ def main():
     check_dashboard()
     check_modules(cfg)
     print(f"\n{'all good' if not FAILS else f'{FAILS} problem(s) to fix'}")
+    # Most people should not work through the setup docs by hand. If the
+    # skills are installed, say so exactly when it is useful: after a report
+    # that lists things to fix.
+    if FAILS and (seo_config.INSTANCE / ".claude" / "skills" / "n-seo-setup" / "SKILL.md").exists():
+        print(
+            "\nnot sure what to do with these? this instance ships the fixes as skills.\n"
+            f"  cd {seo_config.INSTANCE} && claude\n"
+            '  "set this up for my sites"   → /n-seo-setup works through every item above'
+        )
     return 1 if FAILS else 0
 
 

package/ops/export_static.py

@@ -103,11 +103,16 @@ 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)
-
-        (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")
+            dest.write_text(html, encoding="utf-8")
+
+        (out / "styles.css").write_text(fetch("/styles.css"), encoding="utf-8")
+        # styles.css declares @font-face against /fonts/, so the file has to
+        # travel with it or every heading in the mirror falls back silently.
+        fonts = ROOT / "public" / "fonts"
+        if fonts.is_dir():
+            shutil.copytree(fonts, out / "fonts")
+        (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:

package/ops/templates/n-seo-daily-task.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-16"?>
+<!--
+  n-seo daily run at 07:00 local, for Windows Task Scheduler.
+
+  Register it (from an elevated or normal prompt, your choice — this is a
+  per-user task):
+
+    schtasks /create /tn "n-seo daily" /xml ops\templates\n-seo-daily-task.xml
+
+  Before you do, replace the two placeholders below:
+    __NSEO__     the n-seo command, e.g. C:\Users\you\AppData\Roaming\npm\n-seo.cmd
+                 (find it with:  where n-seo)
+    __INSTANCE__ your instance directory, e.g. C:\Users\you\my-sites
+
+  StartWhenAvailable is the Windows equivalent of launchd's catch-up
+  behaviour: a machine that was asleep at 07:00 runs the job when it wakes,
+  rather than skipping the day the way cron does.
+-->
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>n-seo daily run: pulls Search Console and GA4, probes the sites, refreshes the queue.</Description>
+    <URI>\n-seo daily</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <StartBoundary>2026-01-01T07:00:00</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay>
+        <DaysInterval>1</DaysInterval>
+      </ScheduleByDay>
+    </CalendarTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>true</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT2H</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>__NSEO__</Command>
+      <Arguments>daily --instance "__INSTANCE__"</Arguments>
+      <WorkingDirectory>__INSTANCE__</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "n-seo",
-  "version": "0.1.1",
-  "description": "Local-first SEO / AEO / GEO control plane: pulls Search Console + GA4, probes your sites, and turns the data into a ranked action queue you can act on without an agency.",
+  "version": "0.3.0",
+  "description": "Agentic, local-first SEO / AEO / GEO control plane: pulls Search Console + GA4, probes your sites, and ranks the next moves. Your LLM writes the proposals; your coding agent works the queue over MCP.",
   "license": "MIT",
   "author": "En Dash Consulting (https://endash.us)",
   "homepage": "https://n-seo.dev/",
@@ -16,12 +16,19 @@
     "seo",
     "aeo",
     "geo",
+    "agent",
+    "ai-agent",
+    "agentic",
+    "llm",
+    "claude",
+    "claude-code",
+    "mcp",
+    "mcp-server",
     "search-console",
     "google-analytics",
     "ga4",
     "llms-txt",
     "ai-crawlers",
-    "mcp",
     "dashboard",
     "local-first",
     "cli"
@@ -40,6 +47,14 @@
     "public/",
     "n-seo.config.example.json",
     ".env.example",
+    ".claude/skills/orient/",
+    ".claude/skills/n-seo-setup/",
+    ".claude/skills/n-seo-add-site/",
+    ".claude/skills/n-seo-triage/",
+    ".claude/skills/n-seo-ship/",
+    ".claude/skills/n-seo-review/",
+    ".claude/skills/n-seo-deploy/",
+    "!.claude/skills/README.md",
     "docs/",
     "README.md",
     "LICENSE"
@@ -53,18 +68,18 @@
     "typecheck": "tsc --noEmit",
     "mcp": "tsx src/mcp-stdio.ts",
     "mcp:smoke": "node ops/mcp-smoke-stdio.mjs",
-    "doctor": "python3 ops/doctor.py",
-    "demo": "python3 ops/demo_data.py",
-    "daily": "python3 ops/daily.py",
+    "doctor": "node ops/py.mjs ops/doctor.py",
+    "demo": "node ops/py.mjs ops/demo_data.py",
+    "daily": "node ops/py.mjs ops/daily.py",
     "test": "tsx --test tests/ts/*.test.ts",
-    "test:py": "python3 -m unittest discover -s tests/py -v",
+    "test:py": "node ops/py.mjs -m unittest discover -s tests/py -v",
     "check": "npm run typecheck && npm test && npm run test:py",
-    "export": "python3 ops/export_static.py",
+    "export": "node ops/py.mjs ops/export_static.py",
     "docker:build": "docker build -t n-seo:latest .",
     "docker:up": "docker compose -f docker/compose.yml up -d"
   },
   "dependencies": {
-    "@hono/node-server": "^1.13.7",
+    "@hono/node-server": "^2.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "hono": "^4.6.14",
     "tsx": "^4.19.2",

package/probes/site_probe.py

@@ -173,7 +173,7 @@ def main():
     out_dir = seo_config.DATA / "probes"
     out_dir.mkdir(parents=True, exist_ok=True)
     out = out_dir / f"probe-{datetime.now(timezone.utc):%Y%m%d-%H%M%S}.json"
-    out.write_text(json.dumps(snapshot, indent=2))
+    out.write_text(json.dumps(snapshot, indent=2), encoding="utf-8")
 
     for s in snapshot["sites"]:
         h = s["homepage"]

package/public/fonts/OFL.txt

@@ -0,0 +1,105 @@
+The two fonts in this directory are used under the SIL Open Font License 1.1.
+The full license text follows. Both are redistributed unmodified, as the
+latin-subset variable woff2 files Google Fonts serves.
+
+  montserrat-latin-var.woff2
+    Copyright 2024 The Montserrat Project Authors
+    https://github.com/JulietaUla/Montserrat
+
+  merriweather-latin-var.woff2
+    Copyright 2020 The Merriweather Project Authors, with Reserved Font Name
+    "Merriweather". https://github.com/EbenSorkin/Merriweather4
+
+--------------------------------------------------------------------------
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/public/styles.css

@@ -62,6 +62,19 @@
   }
 }
 
+/* Montserrat, self-hosted: one variable file, latin subset, from this origin.
+   Headings and the brand mark only — the tables, chips and numbers stay on the
+   system UI font, which is what a dense data view is designed around. The
+   fallback stack is what renders if the file is missing, so nothing breaks. */
+@font-face {
+  font-family: "Montserrat";
+  src: url("/fonts/montserrat-latin-var.woff2") format("woff2-variations"),
+       url("/fonts/montserrat-latin-var.woff2") format("woff2");
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+
 * { box-sizing: border-box; }
 body {
   margin: 0;
@@ -72,7 +85,7 @@ body {
   line-height: 1.55;
 }
 main { max-width: 1480px; margin: 0 auto; padding: 28px 24px 80px; }
-h1, h2, h3 { line-height: 1.2; letter-spacing: -0.01em; }
+h1, h2, h3 { font-family: "Montserrat", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; line-height: 1.2; letter-spacing: -0.01em; }
 h1 { font-size: 1.8rem; font-weight: 800; margin: 0.5em 0; }
 h2 { font-size: 1.05rem; font-weight: 700; margin: 2em 0 0.6em; text-transform: uppercase; letter-spacing: 0.06em; }
 h2 small { font-weight: 500; color: var(--muted); font-size: 0.75rem; text-transform: none; letter-spacing: 0; }
@@ -544,6 +557,10 @@ footer { max-width: 1480px; margin: 0 auto; padding: 16px 24px 40px; color: var(
 .idx-help { color: var(--muted); font-size: 0.82rem; margin-left: 8px; }
 .idx-stale { color: var(--muted); font-size: 0.72rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; }
 .idx-sitemap { margin: -4px 0 8px; font-size: 0.78rem; color: var(--muted); }
+.idx-fix { margin: 6px 0 2px 8px; font-size: 0.8rem; color: var(--muted); line-height: 1.55; max-width: 96ch; }
+.idx-ri { display: inline-block; font-size: 0.68rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; border-radius: 4px; padding: 1px 6px; margin-right: 4px; white-space: nowrap; }
+.idx-ri.yes { background: var(--good-soft); color: var(--good); }
+.idx-ri.no { background: var(--bad-soft); color: var(--bad); }
 
 /* ---- settings ---- */
 .settings-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 12px; }

package/src/actions.ts

@@ -118,7 +118,7 @@ function probeActions(site: SiteCfg): Action[] {
   const mk = (key: string, title: string, how: string): Action => ({
     id: `gen-hygiene-${slug(site.host)}-${key}`,
     host: site.host, title, kind: "Config change", why: "Live probe failing on this check", how,
-    spec: [how, `Verify with: python3 probes/site_probe.py after deploy.`],
+    spec: [how, `Verify with: n-seo daily --only probe after deploy.`],
     impact: 5, effort: "S", tag: "hygiene", source: "rule",
   });
   if (!p.robots.exists) out.push(mk("robots", "Add robots.txt", "Serve robots.txt with a Sitemap: pointer and explicit AI-crawler allowances."));

package/src/config.ts

@@ -80,7 +80,7 @@ export interface Hooks {
   beforeRun: string[];
   /** … after the last step (and after last-run.json is written) */
   afterRun: string[];
-  /** … after a named step, e.g. { "daily-diff": ["python3 my_sync.py"] } */
+  /** … after a named step, e.g. { "daily-diff": ["node my_sync.mjs"] } */
   afterStep: Record<string, string[]>;
 }
 

package/src/mcp.ts

@@ -273,7 +273,7 @@ export function createMcpServer(): McpServer {
     },
     async ({ host }) => {
       const audit = data.metadataAudit();
-      if (!audit) return fail("No metadata audit on disk yet — run python3 ingest/analyze_metadata.py.");
+      if (!audit) return fail("No metadata audit on disk yet — run `n-seo daily --only metadata-audit`.");
       if (!host) return json(audit);
       const findings = audit.sites[host];
       if (!findings) return fail(`No audit entry for "${host}". Known: ${Object.keys(audit.sites).join(", ")}`);
@@ -379,7 +379,7 @@ export function createMcpServer(): McpServer {
     },
     async () => {
       const scan = data.opportunityScan();
-      if (!scan) return fail("No opportunity scan on disk yet — run python3 ops/opportunity_scan.py.");
+      if (!scan) return fail("No opportunity scan on disk yet — run `n-seo daily --only opportunity-scan`.");
       return json(scan);
     }
   );

package/src/server.tsx

@@ -5,7 +5,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { ROOT, PORT, siteByHost, dotEnv } from "./config.js";
+import { ROOT, INSTANCE, PORT, siteByHost, dotEnv } from "./config.js";
 import { draftBySlug, campaignBySlug } from "./data.js";
 import { allActions } from "./actions.js";
 import { acceptProposal, setWatching, retire } from "./backlog.js";
@@ -94,6 +94,20 @@ app.get("/styles.css", (c) => {
   return c.text(css, 200, { "Content-Type": "text/css; charset=utf-8" });
 });
 
+// The one webfont the dashboard uses, served from this origin. Self-hosting
+// keeps the dashboard free of third-party requests — it renders on machines
+// with no outbound internet, and it never tells Google when someone opens it.
+app.get("/fonts/:file", (c) => {
+  const file = c.req.param("file");
+  if (!/^[\w.-]+\.woff2$/.test(file)) return c.notFound();
+  const abs = path.join(ROOT, "public", "fonts", file);
+  if (!fs.existsSync(abs)) return c.notFound();
+  return c.body(fs.readFileSync(abs), 200, {
+    "Content-Type": "font/woff2",
+    "Cache-Control": "public, max-age=31536000, immutable",
+  });
+});
+
 app.get("/favicon.svg", (c) => {
   const svg = fs.readFileSync(path.join(ROOT, "public", "favicon.svg"), "utf8");
   return c.text(svg, 200, { "Content-Type": "image/svg+xml", "Cache-Control": "public, max-age=86400" });
@@ -257,4 +271,11 @@ app.post("/api/backlog/:id/retire", (c) => {
 const HOST = process.env.SEO_HOST ?? "127.0.0.1";
 serve({ fetch: app.fetch, port: PORT, hostname: HOST }, (info) => {
   console.log(`n-seo → http://${HOST === "0.0.0.0" ? "localhost" : HOST}:${info.port}`);
+  // Printed once per start, and only where it is actionable: an instance that
+  // has the skills installed. A running dashboard says nothing about how to
+  // get the next thing done, and most people should be asking rather than
+  // reading.
+  if (fs.existsSync(path.join(INSTANCE, ".claude", "skills", "n-seo-triage", "SKILL.md"))) {
+    console.log(`      ask it: cd ${INSTANCE} && claude → "what should I work on today?"`);
+  }
 });