n-seo 0.1.1 → 0.3.0

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";
@@ -27,7 +28,9 @@ const USAGE = `n-seo ${PKG.version} — an SEO on your machine
 
 usage: n-seo <command> [--instance <dir>] [args...]
 
-  init [dir]      scaffold an instance directory (default: cwd); never overwrites
+  init [dir]      scaffold a standalone instance directory (default: cwd); never
+                  overwrites, and refuses to scaffold inside a website's repo
+                  (--force overrides)
   start           run the dashboard for the instance
   dev             dashboard with reload on engine code changes
   daily           the morning run (args pass through: --only, --skip, --list, …)
@@ -121,6 +124,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}.`);
@@ -132,8 +144,87 @@ function missingDeps(cmd, what) {
 
 /* ---------- init ---------- */
 
-function init(dirArg) {
+/** Files that mean "this directory is an application", not a place to keep
+ *  search-ops files. n-seo is a standalone project: it writes a config, a
+ *  queue, drafts and a data/ tree that the daily run rewrites every morning.
+ *  Dropped into a website's repo those files get committed, deployed, and
+ *  eventually served — and `n-seo upgrade` starts fighting the site's own
+ *  package.json. The instance sits beside the sites it watches, never inside
+ *  one. */
+const APP_MARKERS = [
+  "package.json", "index.html", "next.config.js", "next.config.mjs", "next.config.ts",
+  "vite.config.js", "vite.config.ts", "astro.config.mjs", "nuxt.config.ts",
+  "svelte.config.js", "gatsby-config.js", "remix.config.js", "angular.json",
+  "Gemfile", "go.mod", "Cargo.toml", "pyproject.toml", "composer.json",
+  "hugo.toml", "config.toml", "_config.yml", "wp-config.php", "Dockerfile",
+];
+
+/** The nearest ancestor holding a .git, or null. */
+function gitRootOf(dir) {
+  let cur = path.resolve(dir);
+  for (;;) {
+    if (fs.existsSync(path.join(cur, ".git"))) return cur;
+    const up = path.dirname(cur);
+    if (up === cur) return null;
+    cur = up;
+  }
+}
+
+/** Why this directory is the wrong place for an instance, or null if it is
+ *  fine.
+ *
+ *  `forChild` means the instance will be a NEW directory created inside
+ *  `dir`, which changes one answer: a repository root is a fine place to put
+ *  an instance (it becomes its own repo) but a terrible parent for one (the
+ *  new directory lands inside that repo's working tree).
+ *
+ *  Re-running init on an existing instance is always allowed. */
+function wrongPlaceFor(dir, forChild = false) {
+  if (fs.existsSync(path.join(dir, "n-seo.config.json"))) return null;
+  // In-place mode: the engine checkout is the instance. It has a package.json
+  // and a .git of its own, both of which would otherwise trip every check.
+  if (!forChild && path.resolve(dir) === ROOT) return null;
+  const marker = APP_MARKERS.find((f) => fs.existsSync(path.join(dir, f)));
+  if (marker) {
+    return forChild
+      ? `${dir} contains ${marker} — an instance created here would sit inside an application`
+      : `${dir} contains ${marker} — that is an application, not an n-seo instance`;
+  }
+  const root = gitRootOf(dir);
+  const insideSomeoneElsesRepo = root && (forChild || root !== path.resolve(dir));
+  if (insideSomeoneElsesRepo && !fs.existsSync(path.join(root, "n-seo.config.json"))) {
+    return `${dir} is inside the git repository at ${root} — the instance would be committed to it`;
+  }
+  return null;
+}
+
+function init(dirArg, force = false) {
   const dir = path.resolve(dirArg ?? process.cwd());
+  // A directory that does not exist yet inherits its parent's problem: a new
+  // folder created inside a site repo is still inside that site repo.
+  const wrong = fs.existsSync(dir) ? wrongPlaceFor(dir) : wrongPlaceFor(path.dirname(dir), true);
+  if (wrong && !force) {
+    console.error(`n-seo init: refusing to scaffold here.
+
+  ${wrong}
+
+n-seo is a standalone project, not something you add to a website. It keeps a
+config, an action queue, content drafts and a data/ tree that the daily run
+rewrites every morning; inside a site repo those get committed and deployed.
+The instance watches your sites over the Search Console API — it never needs
+to live in their code.
+
+Do this instead:
+
+  cd ~            # anywhere outside your site repos
+  n-seo init my-sites
+  cd my-sites
+
+Then list the sites you own in my-sites/n-seo.config.json.
+
+If you really mean it here, pass --force.`);
+    return 2;
+  }
   fs.mkdirSync(dir, { recursive: true });
   const name = path.basename(dir);
   const put = (rel, content) => {
@@ -160,6 +251,59 @@ function init(dirArg) {
     const src = path.join(ROOT, rel);
     put(rel, fs.existsSync(src) ? fs.readFileSync(src, "utf8") : `# ${rel}\n`);
   }
+  // The skills are the product's front door: with them in place the instance
+  // is a directory an agent can be pointed at, and setup / triage / shipping
+  // become a conversation instead of a docs-reading exercise. The engine's
+  // own contributor skills (ndx-*) stay behind — they are for working on
+  // n-seo, not with it. Placeholders become this install's real paths so the
+  // commands in them are copy-pasteable.
+  const INSTANCE_SKILLS = ["orient", "n-seo-setup", "n-seo-add-site", "n-seo-triage", "n-seo-ship", "n-seo-review", "n-seo-deploy"];
+  let skillsCopied = 0;
+  for (const skill of INSTANCE_SKILLS) {
+    const src = path.join(ROOT, ".claude", "skills", skill, "SKILL.md");
+    if (!fs.existsSync(src)) continue;
+    const body = fs
+      .readFileSync(src, "utf8")
+      .replaceAll("<engine checkout>/bin/n-seo.mjs", path.join(ROOT, "bin", "n-seo.mjs"))
+      .replaceAll("<instance dir>", dir);
+    put(path.join(".claude", "skills", skill, "SKILL.md"), body);
+    skillsCopied++;
+  }
+
+  put("CLAUDE.md", `# ${name} — an n-seo instance
+
+This directory is an n-seo instance: config, the curated action queue, content
+drafts, and the data the daily run writes. It is **not** a website. The sites
+it watches live in their own repositories and are read over the Search Console
+and GA4 APIs.
+
+Engine (the code): ${ROOT}
+Docs: ${path.join(ROOT, "docs")}
+
+## Working here
+
+Skills in \`.claude/skills/\` cover the routine work — start with
+\`/orient\` in a fresh session, then \`/n-seo-triage\` for what to do today,
+\`/n-seo-ship\` to implement one card, \`/n-seo-review\` for the weekly pass.
+
+## Rules that are not negotiable
+
+- **28-day metadata freeze.** After a page's title or description changes,
+  leave that page's metadata alone for 28 days. Title churn reads as
+  manipulation and resets Google's evaluation.
+- **At most ~8 title/description changes a week** across all sites.
+- **Impact numbers order the queue. They are not forecasts.** Never report
+  one as an expected result.
+- **Decisions ride the trailing 90 days.** The 16-month data is for totals
+  and history only.
+- **Shipped work becomes \`watching\`, never deleted** — that is how the loop
+  closes.
+- **Machine proposals never self-promote.** They wait in the holding area on
+  /actions until a human accepts them.
+- **Site changes ship as branches and pull requests** in the site's own repo,
+  never committed straight to its main branch.
+`);
+
   const envExample = path.join(ROOT, ".env.example");
   put(".env", fs.existsSync(envExample) ? fs.readFileSync(envExample, "utf8") : "");
   put(".gitignore", "data/\nsite/\n.env\n__pycache__/\nnode_modules/\n");
@@ -193,15 +337,38 @@ n-seo upgrade         # update the engine; your files here are untouched
 
 Edit \`n-seo.config.json\` for sites, Google access, modules and hooks.
 Docs: ${path.join(ROOT, "docs")}
+
+## Or just ask
+
+n-seo is built to be driven by an AI agent. Open this directory in Claude Code
+(or any agent that reads \`.claude/skills/\`) and talk to it:
+
+    "set this up for my sites"      → /n-seo-setup
+    "what should I work on today?"  → /n-seo-triage
+    "do the first one"              → /n-seo-ship
+    "how did last month go?"        → /n-seo-review
+
+A read-only MCP server is wired up in \`.mcp.json\`, so the agent reads the
+same queue and metrics the dashboard shows. It can propose and implement;
+it cannot publish, post, or change your sites behind your back.
 `);
   console.log(`
 instance ready at ${dir}
+  a standalone project — your websites stay in their own repos, untouched
 
 next:
   cd ${dir}
-  edit n-seo.config.json      (sites, google.serviceAccountKey — see ${path.join(ROOT, "docs", "SETUP-GOOGLE.md")})
-  n-seo doctor
-  n-seo demo && n-seo start   (or n-seo daily once the key is in place)
+  n-seo demo && n-seo start   see the dashboard working on synthetic data
+  edit n-seo.config.json      your sites + google.serviceAccountKey
+  n-seo doctor                checks the setup and names what is missing
+
+or hand it to an agent — ${skillsCopied} skills are installed in .claude/skills/:
+  cd ${dir} && claude
+  "set this up for my sites"  → /n-seo-setup walks the whole thing, including
+                                the Google service account and both grants
+  later: "what should I work on today?" → /n-seo-triage
+
+setup guide: ${path.join(ROOT, "docs", "SETUP-GOOGLE.md")}
 `);
   return 0;
 }
@@ -229,14 +396,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,12 +416,12 @@ 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) {
   case "init":
-    code = init(rest[0] ?? flag ?? process.cwd());
+    code = init(rest.find((a) => !a.startsWith("-")) ?? flag ?? process.cwd(), rest.includes("--force"));
     break;
   case "start":
   case "dev":
@@ -274,7 +441,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/ADDING-A-SITE.md

@@ -3,6 +3,10 @@
 One entry in `n-seo.config.json`. There are no per-script site lists:
 every pull, probe, audit, page and export reads the same `sites` array.
 
+> Or say *"add example.com"* in the instance directory: the `n-seo-add-site`
+> skill picks the right property form, finds the numeric GA4 id, proposes a
+> brand regex, and reminds you about both access grants.
+
 ```json
 {
   "host": "docs.example.com",

package/docs/DEPLOY.md

@@ -7,6 +7,10 @@ it sleeps, it travels, and the run silently skips a day.
 
 This document is about moving it to a box that is always on.
 
+> Or say *"get this off my laptop"* in the instance directory — the
+> `n-seo-deploy` skill runs this procedure, and refuses to expose the
+> dashboard port to the internet whatever you ask it for.
+
 ## The shape
 
 One host runs two long-lived things — the dashboard and a scheduler that

package/docs/FAQ.md

@@ -5,6 +5,25 @@ Nothing. The Search Console and GA4 APIs are free within quotas that ordinary
 use never approaches. The optional LLM module runs whatever local command you
 give it; if that is a paid CLI, that is your cost, not the tool's.
 
+**Can I install it inside my website's repository?**
+No — and `n-seo init` refuses to, so you cannot do it by accident. n-seo is a
+standalone project. It writes a config, an action queue, content drafts and a
+`data/` tree that the daily run rewrites every morning; inside a site repo all
+of that gets committed, and usually deployed. It reads your sites through the
+Search Console and GA4 APIs, so it has no reason to sit in their code. Put the
+instance anywhere else — `~/my-sites` is fine — and list the sites you own in
+its config. One instance can watch as many sites as you like. `--force`
+overrides the check if you have a reason.
+
+**Do I have to read all these docs?**
+No. `n-seo init` installs seven skills into your instance, so setup and daily
+use are a conversation: open the directory in Claude Code (or any agent that
+reads `.claude/skills/`) and say "set this up for my sites", "what should I
+work on today?", "do the first one". The agent reads the queue over a
+read-only MCP server, follows the operating rules in the generated
+`CLAUDE.md`, and cannot publish or change a site on its own. The docs are the
+reference behind the skills, not a prerequisite.
+
 **Does it change my site?**
 No. It reads your data, probes your pages, and produces a queue of actions
 with evidence and specs. You make the change in your own repo and ship it.
@@ -28,8 +47,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
@@ -78,12 +108,22 @@ shown flat rather than omitted so you can tell "connected and quiet" from
 "missing from the pipeline."
 
 **The indexing page lists a "Soft 404" for a page that is fine.**
-Check the "last crawled" column. A verdict is only as current as the crawl
-behind it; the page flags verdicts older than 90 days as stale. Request
-indexing and re-check rather than chasing a template bug.
+Check the "last crawled" column first. A verdict is only as current as the
+crawl behind it, and the page flags verdicts older than 90 days as stale — a
+page rewritten since then is being judged on content Google has not seen. For
+a stale verdict, request indexing once and let the recrawl settle it.
+
+For a *fresh* soft 404, requesting indexing is the wrong move: Google already
+fetched the page, got a 200, and decided the content was an error or empty.
+Asking again re-runs the same judgement and spends the daily quota. Fetch the
+URL yourself and pick the real cause — the page renders its content in
+JavaScript and the crawler saw an empty shell, or it is genuinely thin, or it
+is an error page returning 200 and should return 404 or 410 and leave the
+sitemap. Fix that, then request indexing. n-seo's indexing page names the
+check to run for each verdict.
 
 **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/INSTANCE.md

@@ -1,5 +1,29 @@
 # Running n-seo as an engine + instance
 
+> **An instance is a standalone project.** It is never a subdirectory of a
+> website you are optimising. n-seo reads your sites through the Search
+> Console and GA4 APIs; it has no reason to live in their code, and living
+> there means committing and deploying its config, its queue and a `data/`
+> tree that is rewritten every morning.
+
+```
+~/
+├── code/
+│   ├── my-website/         a site you own — untouched
+│   └── docs-site/          another one — untouched
+└── my-sites/               the instance
+    ├── n-seo.config.json   both sites listed here
+    ├── config/backlog.json the curated queue
+    ├── content/            drafts, campaigns
+    ├── .claude/skills/     the operating skills
+    ├── CLAUDE.md           the operating rules
+    └── data/               the daily run's output, gitignored
+```
+
+One instance watches as many sites as you own, and `n-seo init` refuses to
+scaffold into an application directory or a git repository it does not own
+(`--force` overrides).
+
 n-seo can run two ways. In the simplest, you clone the repo, put your config
 in the checkout and run it there. In the second, the checkout is an **engine**
 you never edit, and everything that is yours — config, queue, content, data,
@@ -93,6 +117,36 @@ and `content/campaigns/README.md`, `.env` (from `.env.example`), a
 `.gitignore` that excludes `data/`, `site/` and `.env`, a `.mcp.json` that
 spawns the engine's MCP server with `N_SEO_INSTANCE` set, and a short README.
 
+It also makes the instance agent-ready, which is how most people should drive
+it:
+
+- `.claude/skills/` — the seven operating skills (`orient`, `n-seo-setup`,
+  `n-seo-add-site`, `n-seo-triage`, `n-seo-ship`, `n-seo-review`,
+  `n-seo-deploy`), copied from the engine with this install's real engine and
+  instance paths substituted in, so every command in them is copy-pasteable.
+  The engine's contributor skills (`ndx-*`) are not copied — they are for
+  developing n-seo, not operating it.
+- `CLAUDE.md` — the operating rules an agent working in this directory has to
+  follow: the 28-day freeze, the weekly metadata budget, impact-is-not-a-
+  forecast, decisions on the 90-day window, shipped-becomes-watching,
+  proposals never self-promote, site changes ship as pull requests.
+
+With those two files plus `.mcp.json`, opening the instance in Claude Code is
+enough: it can read the queue and the metrics, and it already knows the rules.
+
+```sh
+cd ~/sites/search-ops && claude
+  "set this up for my sites"        → /n-seo-setup
+  "what should I work on today?"    → /n-seo-triage
+  "do the first one"                → /n-seo-ship
+  "how did last month go?"          → /n-seo-review
+```
+
+Both files are yours once written. `n-seo init` never overwrites, so editing
+`CLAUDE.md` to add your own rules survives every re-run and every engine
+upgrade. To pick up improved skills from a newer engine, delete the ones you
+have not customised and re-run `n-seo init`.
+
 To make `n-seo` a command, link the engine once:
 
 ```sh

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.
@@ -100,6 +102,10 @@ a fresh checkout runs.
 - Acceptance: date × page series for 180 days from both sources.
 - Acceptance: URL Inspection verdict for every sitemap URL (sitemap indexes
   followed one level, ≤400 URLs/host), with sitemap submission state.
+- Acceptance: each coverage state renders with what it means, what to do
+  about it, and whether Request Indexing helps — true only where Google has
+  formed no judgement on the content (unknown, discovered-never-crawled),
+  false where it fetched and declined (soft 404, crawled-not-indexed).
 - Acceptance: metadata audit flags title/query mismatch, CTR below position
   expectation, missing/short/duplicate descriptions, long titles.
 - Acceptance: trend file with branded/generic split, rising/falling queries
@@ -146,7 +152,9 @@ the config with the current values as defaults.
   be marked watching or retired; rule-derived items expose no write buttons.
 - Acceptance: the server binds 127.0.0.1 by default and rejects cross-origin
   POSTs.
-- Acceptance: light and dark themes; no external fonts.
+- Acceptance: light and dark themes; no external fonts — the one webfont is
+  served from the app's own origin, so the dashboard renders identically on a
+  host with no outbound internet and leaks no request to a font CDN.
 
 ## Feature: Settings page [shipped]
 
@@ -204,14 +212,22 @@ instead of a CLI, with the key read from `.env`.
   mode is unchanged when it is unset.
 - Acceptance: `n-seo init|start|dev|daily|doctor|demo|mcp|check|export|
   upgrade|version` behave as documented in `docs/INSTANCE.md`.
+- Acceptance: an instance is a standalone project. `n-seo init` exits 2
+  without writing anything when the target holds an application marker, or
+  when the directory it would create falls inside a git repository that is
+  not an instance; `--force` overrides, re-running on an existing instance
+  succeeds, and in-place mode in the engine checkout is unaffected.
+- Acceptance: `init` installs the seven instance-facing skills and a
+  `CLAUDE.md` with the operating rules, substituting the real engine and
+  instance paths, and leaves the contributor (`ndx-*`) skills behind.
 - Acceptance: `n-seo upgrade` refuses to leave the engine on a commit that
   fails `npm run check` without printing the rollback command.
 
-## Feature: Publish the engine to npm [planned]
+## Feature: Publish the engine to npm [shipped]
 
 - Acceptance: `npm i n-seo` installs a working engine; `npx n-seo init`
   scaffolds an instance; the `files` list excludes tests and the marketing
-  site.
+  site, and includes the instance-facing skills.
 
 ## Feature: Scheduled upgrade with gate [planned]
 
@@ -244,6 +260,10 @@ runs doctor.
   promises (local data, evidence first, briefs-not-acts) and the operating
   rules.
 
-## Feature: Custom domain [planned]
+## Feature: Custom domain [shipped]
 
-`www/CNAME` and URL updates once a domain is chosen.
+`www/CNAME` carries n-seo.dev; analytics are guarded on the hostname so a
+fork's Pages deploy never reports into the project's property.
+
+- Acceptance: typography is self-hosted (latin-subset variable woff2 from the
+  page's own origin), so the site makes no third-party request.

package/docs/SCHEDULING.md

@@ -4,6 +4,10 @@ Two things should always be running: the **dashboard** (a long-lived process
 serving the configured port) and the **daily run** (`ops/daily.py`, once a
 morning). Both are plain processes; pick the scheduler your OS already has.
 
+> Or say *"schedule the morning run"* in the instance directory — the
+> `n-seo-deploy` skill covers scheduling on each platform, and `n-seo-setup`
+> ends here.
+
 ## macOS (launchd)
 
 The install script fills in the templates under `ops/templates/`, copies them
@@ -79,16 +83,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