n-seo 0.1.0 → 0.2.0

package/README.md

@@ -1,39 +1,69 @@
-# n-seo
+# n-seo — En Dash SEO
 
-**An SEO, self-hosted.** Website: https://en-dash-consulting.github.io/n-seo/ · From the makers of [n-dx](https://n-dx.dev).
+**An SEO, self-hosted.** Website: https://n-seo.dev/ · From the makers of [n-dx](https://n-dx.dev).
 
-A local-first control plane for growing organic traffic to your own sites —
-classic search (SEO), answer engines (AEO) and AI assistants that cite sources
-(GEO) — without paying an agency to read Search Console for you.
+[![npm](https://img.shields.io/npm/v/n-seo)](https://www.npmjs.com/package/n-seo)
+[![CI](https://github.com/en-dash-consulting/n-seo/actions/workflows/ci.yml/badge.svg)](https://github.com/en-dash-consulting/n-seo/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/n-seo)](LICENSE)
+
+An agentic, local-first control plane for growing organic traffic to your own
+sites — classic search (SEO), answer engines (AEO) and AI assistants that cite
+sources (GEO) — without paying an agency to read Search Console for you.
 
 It pulls Search Console and GA4 into local JSON, probes your live sites for the
 things that quietly break (robots, sitemap, soft 404s, blocked AI crawlers,
 JS-only shells), and turns all of it into a **ranked queue of concrete actions**:
 which page to retitle, which query to answer, which page never got crawled.
-It runs on hardware you control, on a schedule, and shows you the result on a dashboard.
-
-- **Your data stays on your own hardware.** Nothing is sent anywhere except the
-  Google APIs you authorize and, optionally, a local LLM command you choose.
-- **It briefs you; it never posts for you.** Community modules find threads
-  and write a briefing. The words are always yours.
-- **It proposes; you ship.** No module edits your site. The queue tells you
-  what to change and why, with the numbers; you make the change in your own
-  repo and the next day's data tells you whether it worked.
+That part is plain deterministic code. Everything that needs judgment is handed
+to **a model you choose**, and everything that changes a site is handed to you.
+
+- **Your model, whichever you pick.** Point the `llm` module at any CLI that
+  reads a prompt on stdin (`claude -p`, `ollama run`, a shell script) or at an
+  HTTP endpoint — Anthropic, or anything OpenAI-compatible. It writes the
+  proposals, the verdicts on shipped work, and the community briefings. No key
+  ships with n-seo. Leave it off and you still get the full data-derived queue.
+- **Your coding agent, on the queue.** A read-only MCP server exposes the same
+  data the dashboard reads, so Claude Code — or any MCP client — can answer
+  "what should I do first this week?" and then go implement it. Six skills ship
+  with it, so the operating rules are enforced rather than merely documented.
+- **It proposes; it never acts.** No module edits a site, sends an email or
+  posts a comment. Machine proposals wait in a holding area until you accept
+  them. Your data stays on your hardware: nothing leaves the host except the
+  Google APIs you authorize and the provider you configured yourself.
 
 ![Overview](docs/screenshots/overview.png)
 
 ## Quickstart (5 minutes, no Google setup)
 
+```sh
+npm install -g n-seo
+n-seo init my-sites && cd my-sites
+n-seo demo          # a synthetic dataset for example.com
+n-seo start         # dashboard → http://localhost:4600
+```
+
+Open http://localhost:4600. Every page is populated from the demo data, so you
+can see what the tool does before you connect anything. `n-seo demo --clean`
+removes it.
+
+Prefer not to install globally? `npx n-seo init my-sites` works the same way.
+
+<details>
+<summary>Or run it from a clone, if you want to change the engine itself</summary>
+
 ```sh
 git clone https://github.com/en-dash-consulting/n-seo.git
 cd n-seo
 npm install
-npm run demo        # writes a synthetic dataset for example.com under data/
-npm start           # dashboard → http://localhost:4600
+npm run demo
+npm start
 ```
 
-Open http://localhost:4600. Every page is populated from the demo data, so you
-can see what the tool does before you connect anything.
+In this mode the config, queue and data live inside the checkout. That is the
+right shape for hacking on n-seo; for running it, the instance layout above
+keeps your files separate from the engine so upgrades are a reinstall rather
+than a merge. See [docs/INSTANCE.md](docs/INSTANCE.md).
+</details>
 
 ## Connect your real sites
 
@@ -61,6 +91,85 @@ Adding another site later is one entry in the config —
 Running several people's sites, or want upgrades to be a `git pull`? Keep your
 config in its own directory — see [docs/INSTANCE.md](docs/INSTANCE.md).
 
+## Agentic by design
+
+Two things are agentic here, and they are separate. Inside n-seo, the daily run
+hands its findings to a model you configure. Alongside n-seo, your own coding
+agent reads the queue over MCP and does the work.
+
+### Your model, on your findings
+
+The `llm` module is off by default. Turn it on and point it at a provider, and
+the morning run stops being a report:
+
+- **Proposals** — rising queries nothing in the queue covers become concrete
+  cards: the page to write, the section to add, with the numbers cited.
+- **Verdicts** — shipped work is judged against its own success criterion:
+  succeeded, failed, or still cooking.
+- **Briefings** — for each community thread worth joining, the gist, the
+  debate, and where your genuine experience connects.
+
+Reach it two ways, in `n-seo.config.json`:
+
+```jsonc
+// a CLI — anything that reads a prompt on stdin and prints a reply
+"llm": {
+  "enabled": true,
+  "command": "claude -p --model claude-sonnet-5",   // or `llm -m gpt-4o`, `ollama run llama3`, a script
+  "fastCommand": "claude -p --model haiku"          // optional: cheaper, for the high-volume calls
+}
+
+// or an HTTP endpoint — for containers and servers with no CLI signed in
+"llm": {
+  "enabled": true,
+  "http": {
+    "provider": "anthropic",                 // or "openai" for anything OpenAI-compatible
+    "model": "claude-sonnet-5",
+    "fastModel": "claude-haiku-4-5-20251001",
+    "apiKeyEnv": "ANTHROPIC_API_KEY",        // read from the env or .env; no key ships with n-seo
+    "baseUrl": ""                            // optional: a gateway or a local server
+  }
+}
+```
+
+`provider: "openai"` speaks the OpenAI chat-completions shape, so it also covers
+the many gateways and local servers that emulate it. `http` wins when it is
+configured and its key resolves; otherwise the CLI path runs. Proposals land in
+a holding area on `/actions` marked PROPOSED; accepting one into the queue is a
+click a human makes. Nothing that comes back is applied automatically.
+
+### Your coding agent, on the queue
+
+The repo ships an MCP server over the same data the dashboard reads, so an
+agent can answer "what should I do first this week?" from the actual queue
+instead of scraping pages: 16 tools and 3 doc resources, every one annotated
+read-only. `.mcp.json` registers it for Claude Code automatically; Claude
+Desktop, stdio and authenticated HTTP clients are covered in
+[docs/MCP.md](docs/MCP.md). `CLAUDE.md` holds the operating rules an agent
+working here has to follow.
+
+Skills ship for the work itself, so the rules are enforced rather than
+merely documented — six that operate an instance, plus `orient` to get
+current in a fresh session:
+
+| Skill | Use it when |
+|---|---|
+| `n-seo-setup` | Fresh clone to first real daily run, including Google access |
+| `n-seo-add-site` | Adding a site: property form, `gscHost`, GA4 id, brand regex, grants |
+| `n-seo-triage` | "What should I work on today" from the queue and the last run |
+| `n-seo-ship` | Implement one queue card in the site's repo, then record it as watching |
+| `n-seo-review` | The weekly pass: judge watching items, retire what is done, refresh insights |
+| `n-seo-deploy` | Moving n-seo off the laptop onto an always-on host, on a schedule |
+| `orient` | First thing in a fresh session — get current in a few reads |
+
+`n-seo-ship` stops rather than crossing the 28-day title freeze or the weekly
+metadata budget. `.claude/skills/README.md` explains which skills operate an
+instance and which are contributor tooling for developing the engine with
+[n-dx](https://n-dx.dev).
+
+Read-only is the point: an agent can reason over your search data all day and
+still cannot bypass the freeze, the batching, or you.
+
 ## What you get
 
 | Page | What it shows |
@@ -99,7 +208,7 @@ on the Settings page or in `n-seo.config.json`.
 | `indexStatus` | Asks the URL Inspection API whether each sitemap URL is indexed | Search Console access | on |
 | `metadataAudit` | Fetches each ranking page's live title/description and scores them against its queries | nothing extra | on |
 | `opportunityScan` | Refreshes trend analysis; flags rising queries no queue item covers | nothing extra | on |
-| `llm` | Runs a local command (default: the `claude` CLI) for scan proposals and digest briefings | any CLI that reads a prompt on stdin | off |
+| `llm` | Hands the run's findings to the model you choose: scan proposals, verdicts on shipped work, community briefings | a provider you configure: any stdin CLI, or an Anthropic / OpenAI-compatible endpoint | off |
 | `hackerNews` | Finds fresh HN threads in your expertise areas and briefs you | your HN username (optional) | off |
 | `reddit` | The same for subreddits | a free Reddit "script" app's credentials in `.env` | off |
 | `indexNow` | Generates a key and pings Bing/Copilot/Yandex with changed URLs | nothing (does nothing for Google) | off |
@@ -107,30 +216,6 @@ on the Settings page or in `n-seo.config.json`.
 | `gitAutoCommit` | Commits (and pushes) the daily log and export after each run | a git remote, if you want the push | off |
 | `notifications` | macOS notification when a daily step fails | macOS | off |
 
-## Working with an AI agent
-
-The repo ships an MCP server over the same data the dashboard reads, so an
-agent can answer "what should I do first this week?" from the actual queue
-instead of scraping pages. `.mcp.json` registers it for Claude Code
-automatically; Claude Desktop and HTTP clients are covered in
-[docs/MCP.md](docs/MCP.md). It is read-only by design, and `CLAUDE.md` holds
-the operating rules an agent working here has to follow.
-
-It also ships skills for the work itself, so the rules are enforced rather
-than merely documented:
-
-| Skill | Use it when |
-|---|---|
-| `orient` | First thing in a fresh session — get current in a few reads |
-| `n-seo-setup` | Fresh clone to first real daily run, including Google access |
-| `n-seo-add-site` | Adding a site: property form, `gscHost`, GA4 id, brand regex, grants |
-| `n-seo-triage` | "What should I work on today" from the queue and the last run |
-| `n-seo-ship` | Implement one queue card in the site's repo, then record it as watching |
-| `n-seo-review` | The weekly pass: judge watching items, retire what is done, refresh insights |
-
-`.claude/skills/README.md` explains which skills operate an instance and which
-are contributor tooling for developing the engine with [n-dx](https://n-dx.dev).
-
 ## Working with n-dx
 
 The repo is wired for [n-dx](https://n-dx.dev): `docs/PRD.md` is the product
@@ -175,9 +260,10 @@ accept; community participation is human. The reasoning is in
 
 ## Requirements
 
-Node 20 or newer, Python 3.10 or newer, `curl`, `openssl`. macOS or Linux.
-Python is stdlib-only (no pip); the TypeScript app runs under `tsx` with no
-build step.
+Node 20 or newer, Python 3.10 or newer, and `curl`. macOS, Linux or Windows
+10+, all three exercised by CI on every commit. Python is stdlib-only (no
+pip); the TypeScript app runs under `tsx` with no build step. Nothing needs
+`openssl`, `gcloud` or a compiler.
 
 ## Contributing and license
 

package/bin/n-seo.mjs

@@ -14,6 +14,7 @@
  *   n-seo upgrade         git pull + npm ci + npm run check, with a rollback hint
  */
 import { spawnSync, execFileSync } from "node:child_process";
+import { pythonBin } from "../ops/py.mjs";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -121,6 +122,15 @@ function tsxBin() {
   }
 }
 
+/* npm, npx and similar arrive as `.cmd` batch shims on Windows, which
+ * spawnSync cannot execute without a shell — a bare `npm` fails there with
+ * ENOENT. (The Python interpreter has the same problem; ops/py.mjs solves
+ * it, and this file imports pythonBin from there so the CLI and the npm
+ * scripts resolve the interpreter identically.) */
+function npmBin(name = "npm") {
+  return process.platform === "win32" ? `${name}.cmd` : name;
+}
+
 function missingDeps(cmd, what) {
   const installed = ROOT.includes(`${path.sep}node_modules${path.sep}`);
   console.error(`${cmd} needs ${what}.`);
@@ -229,14 +239,14 @@ function upgrade(instance) {
   }
   if (sha256(path.join(ROOT, "package-lock.json")) !== lockBefore || !fs.existsSync(path.join(ROOT, "node_modules"))) {
     console.log("lockfile changed — npm ci");
-    r = spawnSync("npm", ["ci"], { cwd: ROOT, stdio: "inherit" });
+    r = spawnSync(npmBin(), ["ci"], { cwd: ROOT, stdio: "inherit" });
     if (r.status !== 0) {
       console.error(`npm ci failed. Roll back with:\n  git -C ${ROOT} reset --hard ${before}`);
       return r.status ?? 1;
     }
   }
   console.log("running the engine's checks");
-  r = spawnSync("npm", ["run", "check"], { cwd: ROOT, stdio: "inherit", env: { ...process.env, N_SEO_INSTANCE: instance } });
+  r = spawnSync(npmBin(), ["run", "check"], { cwd: ROOT, stdio: "inherit", env: { ...process.env, N_SEO_INSTANCE: instance } });
   if (r.status !== 0) {
     console.error(`\nengine checks FAILED at ${after ?? "?"}. Previous commit: ${before ?? "?"}. Roll back with:\n  git -C ${ROOT} reset --hard ${before}\n  (then npm ci in ${ROOT} if the lockfile moved)`);
     return 1;
@@ -249,7 +259,7 @@ function upgrade(instance) {
 
 const { cmd, instance: flag, rest } = parseArgs(process.argv.slice(2));
 const instance = resolveInstance(flag);
-const py = process.env.PYTHON ?? "python3";
+const py = pythonBin();
 let code = 0;
 
 switch (cmd) {
@@ -274,7 +284,7 @@ switch (cmd) {
   case "check":
     // The self-test needs devDependencies, which an npm install omits.
     code = resolvePkgDir("typescript")
-      ? run("npm", ["run", "check", "--silent", "--", ...rest], instance)
+      ? run(npmBin(), ["run", "check", "--silent", "--", ...rest], instance)
       : missingDeps(cmd, "the engine's dev dependencies (it is the engine's own test suite)");
     break;
   case "daily":

package/docs/FAQ.md

@@ -28,8 +28,19 @@ proposals and verdicts to the opportunity scan and briefings to the digests.
 Nothing it produces is applied automatically.
 
 **Does it run on Windows?**
-Not supported. The scripts assume `curl`, `openssl`, POSIX paths and one of
-launchd / cron / systemd. WSL2 is likely to work but is untested.
+Yes, since 0.2.0, and CI runs the full test suite on Windows on every commit
+rather than taking the claim on trust. You need Node 20+ and Python 3.10+;
+`curl` ships with Windows 10 and later. There is no `openssl` requirement on
+any platform any more — the service-account JWT is signed with node's crypto
+module. Schedule the daily run with Task Scheduler, using the task definition
+in `ops/templates/n-seo-daily-task.xml` (see [SCHEDULING.md](SCHEDULING.md)).
+
+Two differences worth knowing. Commands in the `hooks` block go to `cmd.exe`
+rather than `/bin/sh`, so write them in its syntax or point them at a script.
+And use `n-seo daily` (or `npm run daily`) rather than `python3 ops/daily.py`:
+Windows installs Python as `python`, and the `python3.exe` it ships is a stub
+that opens the Microsoft Store instead of running anything. The CLI finds the
+real interpreter for you, and `$PYTHON` overrides it.
 
 **Where does my data go?**
 Into `data/` on the machine that runs the pipeline, as JSON. The only network
@@ -83,7 +94,7 @@ behind it; the page flags verdicts older than 90 days as stale. Request
 indexing and re-check rather than chasing a template bug.
 
 **A daily step failed. What now?**
-Open `/logs` (or `data/daily-ops.log`), then `python3 ops/doctor.py`. A 401
+Open `/logs` (or `data/daily-ops.log`), then run `n-seo doctor`. A 401
 or 403 from Google means the service account lost access or the key file
 moved. A run that fails every network step at once was offline; the next run
 will recover. Steps are independent — one failing does not stop the others.

package/docs/MCP.md

@@ -1,10 +1,22 @@
-# MCP server — the same data, for agents
-
-`src/mcp.ts` exposes the control plane over the Model Context Protocol so an
-AI agent can read the queue and the metrics directly instead of scraping the
-dashboard. It is **read-only by design**: the queue is edited through the
-dashboard's accept/watch/retire flow, so nothing here writes anything. Every
-tool is annotated `readOnlyHint`.
+# MCP server — your agent, on the queue
+
+n-seo has two agentic surfaces. Inside the daily run, the `llm` module hands
+the findings to a model you configure and gets back proposals, verdicts and
+briefings (see the README). This document is the other one: `src/mcp.ts`
+exposes the control plane over the Model Context Protocol, so the coding agent
+you already use — Claude Code, Claude Desktop, or any MCP client — reads the
+real queue and the real metrics instead of scraping the dashboard, then goes
+and implements the work in your site's repo.
+
+The division of labour is the point. n-seo decides *what is worth doing*, from
+data, with the evidence attached. Your agent does the doing, in the repo where
+the change belongs, under the rules in `CLAUDE.md`.
+
+It is **read-only by design**: the queue is edited through the dashboard's
+accept/watch/retire flow, so nothing here writes anything. All 16 tools and 3
+doc resources are annotated `readOnlyHint`. An agent can reason over your
+search data all day and still cannot bypass the 28-day title freeze, the
+weekly metadata budget, or you.
 
 ## Two transports
 
@@ -65,7 +77,7 @@ another device, tunnel to the dashboard port (Tailscale, `cloudflared`,
 an SSH tunnel) rather than exposing it — the bearer token is the only thing
 in front of it.
 
-## Tools
+## Tools (16)
 
 | Tool | Returns |
 |---|---|
@@ -84,8 +96,9 @@ in front of it.
 | `conversions_status` | Whether conversion events are instrumented and their 28-day counts by source |
 | `campaigns` | Outreach campaigns from `content/campaigns/` — targets, plan, template ids |
 | `settings` | The effective config: sites, module switches, auth mode (never the key) |
+| `engine_info` | Which engine version, commit and instance directory are running, and which modules are on — check before assuming a feature exists |
 
-Resources: `seo://docs/playbook`, `seo://docs/daily-log`,
+Resources (3): `seo://docs/playbook`, `seo://docs/daily-log`,
 `seo://docs/operating-rules`.
 
 ## Example prompts
@@ -98,6 +111,9 @@ Resources: `seo://docs/playbook`, `seo://docs/daily-log`,
 - "Summarize the last five daily-log entries — what regressed, what moved."
 - "Read the opportunity proposals and tell me which ones are worth accepting
   and why. Don't add anything to the queue."
+- "Take the top striking-distance card for example.com, implement it on a
+  branch in the site's repo, and open the PR." — this is the `n-seo-ship`
+  skill's job; it stops rather than crossing the freeze or the weekly budget.
 
 The rules in `CLAUDE.md` apply to an agent using these tools: it proposes,
 you accept; it never drafts community comments; it reads outputs rather than

package/docs/PRD.md

@@ -52,7 +52,8 @@ with evidence attached, and measure yesterday's changes.
 - Not an auto-publisher, link builder, or comment bot.
 - Not a hosted product; there is no account and no server-side component
   beyond an optional static mirror the owner hosts.
-- Windows is not a target (WSL likely works; untested).
+- Not a hosted control panel for other people's sites; one owner, one
+  instance, their own credentials.
 
 ---
 
@@ -72,9 +73,10 @@ a fresh checkout runs.
 
 ## Feature: Service-account auth without gcloud [shipped]
 
-- Acceptance: with only a service-account JSON key and `openssl` on PATH,
-  `python3 ingest/google_auth.py` mints a token and lists accessible
-  properties.
+- Acceptance: with only a service-account JSON key, `n-seo doctor` mints a
+  token and lists accessible properties. No gcloud, no pip install and no
+  openssl binary: the JWT is signed with node's crypto module, which the
+  dashboard already requires.
 - Acceptance: gcloud impersonation and gcloud user modes remain selectable.
 - Acceptance: `ops/doctor.py` reports the exact email to add in Search
   Console and GA4 and which configured properties are not yet accessible.

package/docs/RELEASING.md

@@ -139,6 +139,27 @@ workflow also deliberately omits `registry-url` from `setup-node`, because it
 writes an `.npmrc` auth line interpolating `NODE_AUTH_TOKEN`, and an empty
 value there produces the same misleading 404.
 
+## Approving a staged release
+
+The trusted publisher is configured to allow `npm stage publish` only, so the
+workflow submits a version and stops. It is not on the registry until a human
+approves it with 2FA. That is deliberate: a compromised runner or a stray tag
+cannot put code on npm that other people's machines will then execute.
+
+After the release run goes green:
+
+```sh
+npm stage list n-seo          # the stage id
+npm stage view <stage-id>     # inspect exactly what CI built
+npm stage approve <stage-id>  # 2FA; now it is live
+```
+
+`npm stage reject <stage-id>` throws it away. The package's Staged Packages
+tab on npmjs.com does the same thing in a browser, which is easier if your
+second factor is a passkey rather than an authenticator app.
+
+The workflow's run summary prints these commands with the version filled in.
+
 ## Verify what was published
 
 Do not trust the workflow's own output. Install from the registry, into an

package/docs/SCHEDULING.md

@@ -79,16 +79,53 @@ loginctl enable-linger "$USER"     # keep user units running when you are logged
 Check on them with `systemctl --user status n-seo-dashboard` and
 `journalctl --user -u n-seo-daily`.
 
+## Windows (Task Scheduler)
+
+`ops/templates/n-seo-daily-task.xml` is a ready task definition. Replace the
+two placeholders in it, then register it:
+
+```bat
+where n-seo
+:: put that path in __NSEO__, and your instance directory in __INSTANCE__
+schtasks /create /tn "n-seo daily" /xml ops\templates\n-seo-daily-task.xml
+```
+
+Check it with `schtasks /query /tn "n-seo daily" /v /fo list`, run it now with
+`schtasks /run /tn "n-seo daily"`, remove it with
+`schtasks /delete /tn "n-seo daily"`.
+
+The task sets `StartWhenAvailable`, which is the Windows equivalent of the
+launchd behaviour above: a machine that was asleep at 07:00 runs the job when
+it wakes rather than skipping the day the way cron does. It also sets
+`RunOnlyIfNetworkAvailable`, so it will not start into a dead connection.
+
+For the dashboard, run `n-seo start` from a terminal, or register a second
+task with the same XML, changing the arguments to `start` and the trigger to
+"At log on".
+
+**Hooks run through `cmd.exe` on Windows.** The `hooks` block in your config
+is handed to the system shell, which is `cmd.exe` there and `/bin/sh`
+elsewhere, so a hook written as `foo && bar` behaves but one relying on
+POSIX quoting, `$VAR` or pipelines into Unix tools will not. Point the hook at
+a `.cmd`/`.ps1` script if it needs to do anything shell-specific.
+
 ## Running by hand
 
 ```sh
-python3 ops/daily.py                   # everything
-python3 ops/daily.py --list            # the step names
-python3 ops/daily.py --only gsc,ga4    # a subset
-python3 ops/daily.py --skip index-status
-python3 ops/daily.py --no-network-wait
+n-seo daily                   # everything
+n-seo daily --list            # the step names
+n-seo daily --only gsc,ga4    # a subset
+n-seo daily --skip index-status
+n-seo daily --no-network-wait
 ```
 
+The CLI is the portable form: it finds the Python interpreter this machine
+actually has. `python3 ops/daily.py` is equivalent on macOS and Linux, but
+Windows has no `python3` — it installs Python as `python`, and the
+`python3.exe` that Windows ships is an App Execution Alias that opens the
+Microsoft Store instead of running anything. From a checkout, `npm run daily`
+works everywhere for the same reason. `$PYTHON` overrides the choice.
+
 Each run appends to `data/daily-ops.log`, writes `data/last-run.json` (which
 the dashboard shows as the run status chip), and appends a dated entry to
 `docs/daily-log.md`. Re-running on the same day replaces that day's entry

package/docs/SETUP-GOOGLE.md

@@ -120,7 +120,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():