n-seo 0.1.0

package/.env.example

@@ -0,0 +1,13 @@
+# Copy to .env — everything here is optional.
+
+# Reddit "script" app credentials (https://www.reddit.com/prefs/apps) — only
+# needed when modules.reddit.enabled is true; Reddit blocks anonymous JSON.
+REDDIT_CLIENT_ID=
+REDDIT_CLIENT_SECRET=
+
+# Bearer token for the HTTP MCP endpoint (POST /mcp). Leave empty to keep the
+# endpoint disabled (it returns 503). stdio MCP needs no token.
+SEO_MCP_TOKEN=
+
+# Override the config file location (default: ./n-seo.config.json)
+# N_SEO_CONFIG=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# n-seo
+
+**An SEO, self-hosted.** Website: https://en-dash-consulting.github.io/n-seo/ · 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.
+
+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.
+
+![Overview](docs/screenshots/overview.png)
+
+## Quickstart (5 minutes, no Google setup)
+
+```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
+```
+
+Open http://localhost:4600. Every page is populated from the demo data, so you
+can see what the tool does before you connect anything.
+
+## Connect your real sites
+
+1. Copy the config and edit the `sites` list:
+   ```sh
+   cp n-seo.config.example.json n-seo.config.json
+   ```
+2. Give the tool read access to Search Console and GA4 — a service account
+   with a JSON key, added as a user in both consoles. Follow
+   [docs/SETUP-GOOGLE.md](docs/SETUP-GOOGLE.md).
+3. Check the setup:
+   ```sh
+   python3 ops/doctor.py
+   ```
+4. Run the pipeline once, then look at the dashboard:
+   ```sh
+   python3 ops/daily.py
+   npm start
+   ```
+5. Schedule it to run every morning: [docs/SCHEDULING.md](docs/SCHEDULING.md).
+
+Adding another site later is one entry in the config —
+[docs/ADDING-A-SITE.md](docs/ADDING-A-SITE.md).
+
+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).
+
+## What you get
+
+| Page | What it shows |
+|---|---|
+| `/` Overview | A **Today** board (fix / approve / publish / comment / ship) and a one-row-per-site strip: sessions, 28-day trend, Google clicks, AI-referral share, probe health |
+| `/actions` | The full ranked queue: machine proposals awaiting your accept, active items, and shipped items being watched. Searchable; every card opens a spec |
+| `/insights` | Rising and falling queries (84 days vs the prior 84), branded vs generic split, AI-referral sessions by month, plus your own written briefing if you keep one |
+| `/trends` | Daily clicks and sessions per site with a per-page heatmap; one time window drives every row |
+| `/content` | Participation briefings (HN, Reddit — opt-in), publish-ready drafts, and outreach campaigns with targets and templates |
+| `/site/:host` | Per-site detail: striking-distance queries, CTR gaps, top queries and pages, landing-page engagement, AI referral sources |
+| `/indexing` | Search Console's verdict on every sitemap URL — indexed, discovered-never-crawled, soft 404 — with stale verdicts flagged |
+| `/probes` | The latest live-site health snapshot for every site |
+| `/logs` | The daily log (one dated entry per run, ALERT lines for regressions) and raw run output |
+| `/settings` | Module switches and digest topics; writes `n-seo.config.json` |
+
+## The action engine
+
+`src/actions.ts` runs a small set of rules over the trailing 90 days of data
+and emits actions with the evidence, the concrete move, a spec, an impact
+estimate (clicks per month, used **only to order the queue**) and an effort
+size. The rules: pages whose title or description miss the queries they rank
+for; queries ranking well but rarely clicked (CTR gaps); queries at position
+5–15 (striking distance); probe hygiene failures; landing pages with high
+traffic and low engagement; 28-day traffic drops. These merge with your own
+strategic backlog in `config/backlog.json`, ranked by impact per unit of
+effort. When something ships you mark it *watching* — it stays in view until
+the data says whether it worked.
+
+## Modules
+
+Everything below is off by default except the three data steps. Toggle them
+on the Settings page or in `n-seo.config.json`.
+
+| Module | What it does | Needs | Default |
+|---|---|---|---|
+| `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 |
+| `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 |
+| `staticExport` | Snapshots the dashboard into `site/` as static HTML | nothing | off |
+| `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
+definition, `.rex/` holds the PRD tree generated from it (`ndx status .` to
+see it, `ndx next .` for the next actionable task), and `.rex/workflow.md`
+carries the project's execution rules. Run `ndx init .` once after cloning to
+create the local analysis caches (they are gitignored).
+
+## Repo layout
+
+```
+n-seo.config.json       your sites, auth, modules (copy from the .example)
+config/                 backlog.json (your strategic queue) · insights.json
+content/                drafts/*.md · campaigns/*.json — shown on /content
+bin/n-seo.mjs           the CLI: init an instance, run it, upgrade the engine
+src/                    dashboard + MCP (Hono, hono/jsx SSR, tsx runtime, no bundler)
+  config.ts   data.ts   actions.ts   backlog.ts   views.tsx   server.tsx   mcp.ts
+ingest/                 pull_gsc.py · pull_ga4.py · pull_timeseries.py · pull_index_status.py
+                        analyze_metadata.py · analyze_trends.py · analyze_gsc.py · analyze_ga4.py
+                        google_auth.py · seo_config.py · http_util.py
+probes/site_probe.py    no-auth live health probe
+ops/                    daily.py · daily_diff.py · opportunity_scan.py · hn_digest.py · reddit_digest.py
+                        export_static.py · indexnow.py · doctor.py · demo_data.py · install-launchd.sh · templates/
+docs/                   setup, scheduling, playbook, operating rules, PRD.md
+                        daily-log.md and reports/ (instance-owned)
+tests/                  TypeScript (node --test via tsx) + Python (unittest)
+.rex/                   n-dx PRD tree, generated from docs/PRD.md
+www/                    the marketing site published to GitHub Pages
+data/                   machine-refreshed snapshots (gitignored, regenerable)
+```
+
+## Operating rules
+
+The tool encodes a few rules that keep SEO work honest. The short version:
+decisions ride the 90-day window; impact numbers order the queue and are not
+forecasts; after changing a title, leave it alone for 28 days; no more than
+about eight metadata changes a week across all sites; shipped work becomes
+*watching*, never deleted; proposals never enter the queue without your
+accept; community participation is human. The reasoning is in
+[docs/OPERATING-RULES.md](docs/OPERATING-RULES.md); the strategy is in
+[docs/PLAYBOOK.md](docs/PLAYBOOK.md).
+
+## 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.
+
+## Contributing and license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT — see [LICENSE](LICENSE).

package/bin/n-seo.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * n-seo — run the engine against an instance directory.
+ *
+ * The engine is wherever this file lives (a git checkout or an npm install);
+ * the instance is `--instance <path>`, else $N_SEO_INSTANCE, else the current
+ * directory. Every command below just sets N_SEO_INSTANCE and runs the
+ * engine's own npm script or Python entry point with cwd = the engine, so the
+ * engine can be upgraded without touching a single instance file.
+ *
+ *   n-seo init [dir]      scaffold an instance directory
+ *   n-seo start           dashboard for the instance in cwd
+ *   n-seo daily --only probe
+ *   n-seo upgrade         git pull + npm ci + npm run check, with a rollback hint
+ */
+import { spawnSync, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+
+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
+  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, …)
+  doctor          setup checker (--offline for local checks only)
+  demo            write a synthetic dataset for the instance's configured sites
+  mcp             the read-only MCP server on stdio (for .mcp.json)
+  export          static export of the dashboard into <instance>/site/
+  check           engine self-test: typecheck + unit tests
+  upgrade         update the engine (git pull / npm ci / check) with a rollback hint
+  version         engine version, commit, paths, mode
+  help            this text
+
+instance = --instance <dir>, else $N_SEO_INSTANCE, else the current directory.
+engine   = ${ROOT}
+`;
+
+function parseArgs(argv) {
+  const out = { cmd: argv[0] ?? "help", instance: undefined, rest: [] };
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === "--instance") {
+      const value = argv[++i];
+      // Silently falling back to the cwd here would point `daily` — and its
+      // afterRun hooks — at the wrong directory.
+      if (!value || value.startsWith("-")) {
+        console.error("--instance needs a directory, e.g. --instance ~/my-sites");
+        process.exit(2);
+      }
+      out.instance = value;
+      continue;
+    }
+    if (argv[i].startsWith("--instance=")) { out.instance = argv[i].slice("--instance=".length); continue; }
+    out.rest.push(argv[i]);
+  }
+  return out;
+}
+
+function gitCommit() {
+  try {
+    return execFileSync("git", ["-C", ROOT, "rev-parse", "--short", "HEAD"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+const isGitEngine = () => fs.existsSync(path.join(ROOT, ".git"));
+
+function resolveInstance(flag) {
+  const p = flag ?? process.env.N_SEO_INSTANCE ?? process.cwd();
+  return path.resolve(p);
+}
+
+function run(cmd, args, instance, opts = {}) {
+  const r = spawnSync(cmd, args, {
+    cwd: ROOT,
+    stdio: "inherit",
+    env: { ...process.env, N_SEO_INSTANCE: instance, ...(opts.env ?? {}) },
+  });
+  if (r.error) {
+    console.error(`could not run ${cmd}: ${r.error.message}`);
+    return 1;
+  }
+  return r.status ?? 1;
+}
+
+/* Resolve the engine's own dependencies.
+ *
+ * A git checkout has them in <engine>/node_modules; an npm install has them
+ * hoisted into the CONSUMER's node_modules, and <engine>/node_modules does not
+ * exist at all. Testing for that directory therefore refused to start a
+ * perfectly good `npm i n-seo` install. Resolution works for both layouts. */
+const engineRequire = createRequire(path.join(ROOT, "package.json"));
+
+function resolvePkgDir(name) {
+  try {
+    return path.dirname(engineRequire.resolve(`${name}/package.json`));
+  } catch {
+    return null;
+  }
+}
+
+/** The engine runs TypeScript through tsx, with no build step. */
+function tsxBin() {
+  const dir = resolvePkgDir("tsx");
+  if (!dir) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.tsx;
+    return rel ? path.join(dir, rel) : null;
+  } catch {
+    return null;
+  }
+}
+
+function missingDeps(cmd, what) {
+  const installed = ROOT.includes(`${path.sep}node_modules${path.sep}`);
+  console.error(`${cmd} needs ${what}.`);
+  console.error(installed
+    ? `  the package looks incomplete — reinstall it: npm i n-seo`
+    : `  run: npm ci   (in ${ROOT})`);
+  return 1;
+}
+
+/* ---------- init ---------- */
+
+function init(dirArg) {
+  const dir = path.resolve(dirArg ?? process.cwd());
+  fs.mkdirSync(dir, { recursive: true });
+  const name = path.basename(dir);
+  const put = (rel, content) => {
+    const p = path.join(dir, rel);
+    if (fs.existsSync(p)) { console.log(`  exists, kept   ${rel}`); return; }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+    console.log(`  created        ${rel}`);
+  };
+  const example = JSON.parse(fs.readFileSync(path.join(ROOT, "n-seo.config.example.json"), "utf8"));
+  example.name = name;
+  put("n-seo.config.json", JSON.stringify(example, null, 2) + "\n");
+  put("config/backlog.json", JSON.stringify({
+    _comment: "Your curated strategic queue. The dashboard merges these with data-derived actions. Add items with evidence (why) and a spec; when something ships, set `watching` to a dated note instead of deleting it. `shippedWatch` maps page URLs to notes so data-derived cards on those pages show as watching too.",
+    actions: [],
+    shippedWatch: {},
+  }, null, 2) + "\n");
+  put("config/insights.json", JSON.stringify({
+    _comment: "Optional hand-written marketer briefing shown on /insights above the live trend tables. verdict: opportunity | warning | momentum | deprioritize. Leave the list empty to show only the live tables.",
+    date: "",
+    insights: [],
+  }, null, 2) + "\n");
+  for (const rel of ["content/drafts/README.md", "content/campaigns/README.md"]) {
+    const src = path.join(ROOT, rel);
+    put(rel, fs.existsSync(src) ? fs.readFileSync(src, "utf8") : `# ${rel}\n`);
+  }
+  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");
+  put(".mcp.json", JSON.stringify({
+    mcpServers: {
+      "n-seo": {
+        command: "node",
+        args: [path.join(ROOT, "bin", "n-seo.mjs"), "mcp"],
+        env: { N_SEO_INSTANCE: dir },
+      },
+    },
+  }, null, 2) + "\n");
+  put("README.md", `# ${name} — an n-seo instance
+
+This directory holds one n-seo instance: the config, the curated queue
+(\`config/backlog.json\`), content (\`content/\`), and the data the daily run
+writes (\`data/\`, gitignored). The engine — the code — lives at:
+
+    ${ROOT}
+
+Run everything from here with the \`n-seo\` CLI (it sets \`N_SEO_INSTANCE\`
+to this directory):
+
+\`\`\`sh
+n-seo doctor          # is the setup complete?
+n-seo demo            # synthetic data to see the dashboard working
+n-seo start           # dashboard on the configured port
+n-seo daily           # the morning run
+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")}
+`);
+  console.log(`
+instance ready at ${dir}
+
+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)
+`);
+  return 0;
+}
+
+/* ---------- upgrade ---------- */
+
+const sha256 = (p) => (fs.existsSync(p) ? createHash("sha256").update(fs.readFileSync(p)).digest("hex") : "");
+
+function upgrade(instance) {
+  if (!isGitEngine()) {
+    console.log("engine installed from npm — run: npm update n-seo");
+    return 0;
+  }
+  const before = gitCommit();
+  const lockBefore = sha256(path.join(ROOT, "package-lock.json"));
+  console.log(`engine ${ROOT} at ${before ?? "?"} — pulling`);
+  let r = spawnSync("git", ["-C", ROOT, "pull", "--ff-only"], { stdio: "inherit" });
+  if (r.status !== 0) {
+    console.error("git pull --ff-only failed — the engine has local changes or diverged; resolve in the engine checkout and retry");
+    return r.status ?? 1;
+  }
+  const after = gitCommit();
+  if (after === before) {
+    console.log("already up to date");
+  }
+  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" });
+    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 } });
+  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;
+  }
+  console.log(`\nengine ${before ?? "?"} → ${after ?? "?"}: checks pass. Restart the dashboard to pick it up.`);
+  return 0;
+}
+
+/* ---------- main ---------- */
+
+const { cmd, instance: flag, rest } = parseArgs(process.argv.slice(2));
+const instance = resolveInstance(flag);
+const py = process.env.PYTHON ?? "python3";
+let code = 0;
+
+switch (cmd) {
+  case "init":
+    code = init(rest[0] ?? flag ?? process.cwd());
+    break;
+  case "start":
+  case "dev":
+  case "mcp": {
+    // Spawn tsx directly rather than through `npm run`, so the command does
+    // not depend on npm resolving a bin from inside node_modules/n-seo.
+    const bin = tsxBin();
+    if (!bin) {
+      code = missingDeps(cmd, "the engine's dependencies");
+      break;
+    }
+    const entry = cmd === "mcp" ? "src/mcp-stdio.ts" : "src/server.tsx";
+    const args = cmd === "dev" ? ["watch", entry] : [entry];
+    code = run(process.execPath, [bin, ...args, ...rest], instance);
+    break;
+  }
+  case "check":
+    // The self-test needs devDependencies, which an npm install omits.
+    code = resolvePkgDir("typescript")
+      ? run("npm", ["run", "check", "--silent", "--", ...rest], instance)
+      : missingDeps(cmd, "the engine's dev dependencies (it is the engine's own test suite)");
+    break;
+  case "daily":
+    code = run(py, [path.join(ROOT, "ops", "daily.py"), ...rest], instance);
+    break;
+  case "doctor":
+    code = run(py, [path.join(ROOT, "ops", "doctor.py"), ...rest], instance);
+    break;
+  case "demo":
+    code = run(py, [path.join(ROOT, "ops", "demo_data.py"), ...rest], instance);
+    break;
+  case "export":
+    code = run(py, [path.join(ROOT, "ops", "export_static.py"), ...rest], instance);
+    break;
+  case "upgrade":
+    code = upgrade(instance);
+    break;
+  case "version": {
+    const mode = instance === ROOT ? "in-place" : "instance";
+    console.log(`n-seo ${PKG.version}${gitCommit() ? ` (${gitCommit()})` : ""}\nengine:   ${ROOT}\ninstance: ${instance}\nmode:     ${mode}`);
+    break;
+  }
+  case "help":
+  case "--help":
+  case "-h":
+    process.stdout.write(USAGE);
+    break;
+  default:
+    console.error(`unknown command: ${cmd}\n`);
+    process.stdout.write(USAGE);
+    code = 2;
+}
+process.exit(code);

package/docs/ADDING-A-SITE.md

@@ -0,0 +1,82 @@
+# Adding a site
+
+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.
+
+```json
+{
+  "host": "docs.example.com",
+  "label": "docs",
+  "gscProperty": "sc-domain:example.com",
+  "gscHost": "docs.example.com",
+  "ga4Property": "987654321",
+  "brand": "example|exmpl",
+  "repo": "../example-docs",
+  "hosting": "GitHub Pages"
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `host` | yes | Canonical hostname. The URL slug in the dashboard (`/site/docs.example.com`) and the directory name under `data/ga4/` |
+| `label` | no | Short display name; defaults to `host` |
+| `gscProperty` | for GSC data | The Search Console property exactly as the console shows it: `sc-domain:example.com` (domain property) or `https://www.example.com/` (URL-prefix property, trailing slash included). Leave empty for a site without Search Console; it will still be probed |
+| `gscHost` | no | Hostname to filter page URLs by when the property covers more than this host (see below). Defaults to `host`. Use the hostname the site actually serves on — `www.example.com` if the apex redirects to www |
+| `ga4Property` | for GA4 data | Numeric GA4 property id (Admin → Property details). Not the `G-…` measurement id. Leave empty for no GA4 |
+| `brand` | no | Case-insensitive regex matching your branded queries, for the branded/generic split on `/insights`. Several hosts on one property are OR-ed together |
+| `repo` | no | Where the site's code lives, shown on the site page so actions can name it |
+| `hosting` | no | Free text, shown on the site page |
+
+## Domain properties and subdomains
+
+A `sc-domain:` property covers every subdomain and protocol. If
+`example.com` and `docs.example.com` are separate sites for you but one
+property in Search Console, give both entries the same `gscProperty` and a
+different `gscHost`. The pull happens once per property (into
+`data/gsc/example.com/`) and each site's pages are filtered by `gscHost` when
+read. URL-prefix properties are per host by nature; each gets its own
+directory.
+
+## Access grants
+
+The service account needs to be a user on the new property in Search Console
+(Full) and on the GA4 property (Viewer). If it is already Viewer at the GA4
+*account* level, new properties under that account inherit it. Details and
+the DNS-verification alternative for stubborn domain properties are in
+[SETUP-GOOGLE.md](SETUP-GOOGLE.md).
+
+## Check, then wait for the next run
+
+```sh
+python3 ops/doctor.py
+```
+
+The doctor confirms the service account can see the property and the GA4
+id resolves. Then either wait for the next scheduled run or run it now:
+
+```sh
+python3 ops/daily.py
+```
+
+The site appears on the overview strip, gets its own `/site/<host>` page, is
+probed, audited, swept for index coverage, and shows on `/trends` — with a
+flat "no traffic recorded yet" row rather than silently missing if the data
+is empty, so a brand-new site is visibly connected even before it ranks.
+
+## Removing a site
+
+Delete its entry. Its data under `data/` stays until you remove it (or run
+`npm run demo -- --clean`, which clears the whole `data/` tree). Backlog
+items for that host in `config/backlog.json` remain and still render on
+`/actions`; retire or delete them.
+
+## Adding a site to the watch list
+
+`watchPages` is a flat list of URLs whose GSC numbers appear in every daily
+log entry. Add the pages you have just changed there so the log tracks them:
+
+```json
+"watchPages": [
+  "https://docs.example.com/getting-started"
+]
+```