n-seo 0.1.0

package/src/actions.ts

@@ -0,0 +1,255 @@
+/** The action engine: turns snapshot data into a ranked, concrete to-do queue.
+ *
+ *  Rule-derived actions are recomputed on every call from the 90-day window,
+ *  then merged with the curated queue in config/backlog.json. Pages listed in
+ *  the backlog's `shippedWatch` map turn their rule-derived cards into
+ *  "watching" entries — the fix shipped; the data decides what happens next. */
+import { SITES, type SiteCfg } from "./config.js";
+import * as data from "./data.js";
+import { BACKLOG, SHIPPED_WATCH, slug, type Action, type Effort } from "./backlog.js";
+
+export type { Action, Effort } from "./backlog.js";
+
+const EFFORT_WEIGHT: Record<Effort, number> = { S: 1, M: 2.5, L: 5 };
+
+/** Impact per unit of effort. Never returns NaN: one unrecognised effort or a
+ *  non-numeric impact would otherwise make the sort comparator return NaN and
+ *  leave the order of the entire queue undefined. backlog.ts coerces on load;
+ *  this is the second line of defence for any other producer. */
+export const score = (a: Action) =>
+  (Number.isFinite(a.impact) ? a.impact : 0) / (EFFORT_WEIGHT[a.effort] ?? EFFORT_WEIGHT.M);
+
+const WINDOW_MONTHS = 3; // decision window = trailing 90 days
+
+const pathOf = (url: string): string => "/" + url.split("/").slice(3).join("/");
+const gid = (tag: string, page: string) => `gen-${tag}-${slug(page) || "root"}`;
+
+/** query -> the page that ranks for it (top impressions), host-filtered */
+function topPageForQueries(site: SiteCfg): Map<string, string> {
+  const best = new Map<string, { page: string; imps: number }>();
+  for (const r of data.rawQueryPage(site, true)) {
+    const cur = best.get(r.keys[0]);
+    if (!cur || r.impressions > cur.imps) best.set(r.keys[0], { page: r.keys[1], imps: r.impressions });
+  }
+  return new Map([...best.entries()].map(([q, v]) => [q, v.page]));
+}
+
+function ctrGapActions(site: SiteCfg): Action[] {
+  const gaps = data.ctrGaps(site);
+  if (!gaps.length) return [];
+  const watch = SHIPPED_WATCH();
+  const pageFor = topPageForQueries(site);
+  const byPage = new Map<string, (data.GscRow & { expected: number })[]>();
+  for (const g of gaps) {
+    const page = pageFor.get(g.keys[0]) ?? `https://${site.gscHost}/`;
+    byPage.set(page, [...(byPage.get(page) ?? []), g]);
+  }
+  return [...byPage.entries()].map(([page, qs]) => {
+    const missed = qs.reduce((s, q) => s + (q.impressions / WINDOW_MONTHS) * (q.expected - q.ctr), 0);
+    const top = qs.slice(0, 3).map((q) => `“${q.keys[0]}” (${q.impressions.toLocaleString()} imps, ${(100 * q.ctr).toFixed(1)}% CTR at pos ${q.position.toFixed(1)})`);
+    const watching = watch[page];
+    return {
+      id: gid("ctr-gap", page),
+      host: site.host,
+      title: `Rewrite title/description: ${pathOf(page)}`,
+      kind: "Meta/template change — no new content",
+      why: `Ranks but rarely clicked (90d) — ${top.join("; ")}`,
+      how: `Make the <title> restate the query as its answer; description = 150-char direct answer. Then request reindexing in Search Console.`,
+      spec: [
+        `Page: ${page}`,
+        `Queries being lost: ${qs.map((q) => `“${q.keys[0]}” (${q.impressions.toLocaleString()} imps, ${(100 * q.ctr).toFixed(1)}% CTR, pos ${q.position.toFixed(1)})`).join(" · ")}`,
+        `Title formula: [query phrased as its answer] — [differentiator]. Keep under ~60 chars; front-load the query words.`,
+        `Description: one ~150-char sentence that directly answers the query (this becomes the SERP snippet).`,
+        `Ship: meta change only — no body-content edits needed. Then Search Console → URL Inspection → Request Indexing.`,
+        `Success: CTR on these queries reaches ≥ half of position-expected within 28 days (watch on this dashboard). Then leave the title alone — title churn resets Google's evaluation.`,
+      ],
+      impact: Math.round(missed),
+      effort: "S" as Effort,
+      tag: "ctr-gap",
+      source: "rule" as const,
+      ...(watching ? { watching } : {}),
+    };
+  });
+}
+
+function strikingActions(site: SiteCfg): Action[] {
+  const rows = data.strikingDistance(site).slice(0, 12);
+  if (!rows.length) return [];
+  const watch = SHIPPED_WATCH();
+  const pageFor = topPageForQueries(site);
+  const byPage = new Map<string, data.GscRow[]>();
+  for (const r of rows) {
+    const page = pageFor.get(r.keys[0]) ?? `https://${site.gscHost}/`;
+    byPage.set(page, [...(byPage.get(page) ?? []), r]);
+  }
+  return [...byPage.entries()].map(([page, qs]) => {
+    const imps = qs.reduce((s, q) => s + q.impressions, 0);
+    const impact = Math.round((imps / WINDOW_MONTHS) * 0.06);
+    const top = qs.slice(0, 3).map((q) => `“${q.keys[0]}” pos ${q.position.toFixed(1)} (${q.impressions.toLocaleString()} imps)`);
+    const watching = watch[page];
+    return {
+      id: gid("striking", page),
+      host: site.host,
+      title: `Push to page 1: ${pathOf(page)}`,
+      kind: "Content addition to an existing page",
+      why: `Position 5–15 in the last 90d for ${top.join("; ")}`,
+      how: `Add a section that answers these queries verbatim (H2 phrased as the query + direct answer), add 2–3 internal links to this page from related pages, refresh dateModified.`,
+      spec: [
+        `Page: ${page}`,
+        `Target queries: ${qs.map((q) => `“${q.keys[0]}” (pos ${q.position.toFixed(1)}, ${q.impressions.toLocaleString()} imps)`).join(" · ")}`,
+        `Add one H2 per query cluster, phrased as the query, followed by a 40–60 word direct answer, then detail.`,
+        `Internal links: 2–3 links to this page from the site's highest-authority related pages, using the query as anchor text.`,
+        `Freshness: a real content change → dateModified updates → sitemap lastmod moves.`,
+        `Success: these queries move from pos 5–15 into the top 5 within ~6 weeks.`,
+      ],
+      impact,
+      effort: "M" as Effort,
+      tag: "striking",
+      source: "rule" as const,
+      ...(watching ? { watching } : {}),
+    };
+  }).filter((a) => a.impact >= 1);
+}
+
+function probeActions(site: SiteCfg): Action[] {
+  const p = data.probeFor(site);
+  if (!p) return [];
+  const out: 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.`],
+    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."));
+  if (!p.sitemap.exists) out.push(mk("sitemap", "Add sitemap.xml", "Generate one with honest lastmod dates, reference it from robots.txt, submit it in Search Console."));
+  if (!p["llms.txt"].exists) out.push(mk("llms", "Add llms.txt", "A markdown site summary with links to the key pages — the surface AI crawlers read first."));
+  if (!p.soft_404.real_404) out.push(mk("soft404", "Fix soft 404s", "Unknown paths must return HTTP 404, not 200 — soft 404s waste crawl budget and dilute the index."));
+  if ((p.robots.ai_crawlers_blocked?.length ?? 0) > 0)
+    out.push(mk("ai-block", `Unblock AI crawlers (${p.robots.ai_crawlers_blocked!.join(", ")})`, "Remove the Disallow rules — blocked AI crawlers can't cite the site."));
+  if ((p.homepage.visible_text_bytes ?? 0) < 500 && p.homepage.status === 200)
+    out.push({ ...mk("ssr", "Server-render homepage content", "AI crawlers don't run JS — add static H1 + intro text to the shell."), impact: 15, effort: "M" });
+  return out;
+}
+
+function engagementActions(site: SiteCfg): Action[] {
+  const watch = SHIPPED_WATCH();
+  return data
+    .landingPages(site)
+    .filter((l) => l.sessions >= 30 && l.engagement < 0.25 && l.page !== "(not set)")
+    .slice(0, 3)
+    .map((l) => {
+      const url = `https://${site.gscHost}${l.page}`;
+      // GA landing paths carry no trailing slash; shippedWatch keys may have one
+      const watching = watch[url] ?? watch[`${url}/`];
+      return {
+        id: gid("engagement", url),
+        host: site.host,
+        title: `Fix content mismatch: ${l.page}`,
+        kind: "Content rewrite of an existing page",
+        why: `${l.sessions.toLocaleString()} sessions/90d land here but only ${(100 * l.engagement).toFixed(0)}% engage — the page isn't delivering what the click promised`,
+        how: `Read the top queries landing here, rewrite the opening to deliver that answer immediately, move setup/context below.`,
+        spec: [
+          `Page: ${url}`,
+          `Evidence: ${l.sessions.toLocaleString()} sessions/90d, ${(100 * l.engagement).toFixed(0)}% engagement (a healthy content page sits around 40–70%).`,
+          `Check this site's queries for the ones landing on this path — the rewrite must answer THOSE in the first screenful.`,
+          `Keep the URL; rewrite opening + structure, don't relocate.`,
+          `Success: engagement above 35% within 28 days of shipping.`,
+        ],
+        impact: Math.round((l.sessions / 3) * 0.3),
+        effort: "M" as Effort,
+        tag: "engagement",
+        source: "rule" as const,
+        ...(watching ? { watching } : {}),
+      };
+    });
+}
+
+function trendActions(site: SiteCfg): Action[] {
+  const t = data.sessionTrend(site);
+  if (t.prior >= 50 && t.recent < t.prior * 0.75) {
+    return [{
+      id: `gen-trend-${slug(site.host)}`,
+      host: site.host,
+      title: `Investigate traffic drop`,
+      kind: "Investigation",
+      why: `Sessions down ${(100 * (1 - t.recent / t.prior)).toFixed(0)}% — ${t.recent.toLocaleString()} last 28d vs ${t.prior.toLocaleString()} prior`,
+      how: `Check Search Console for position/impression drops by page, the probe for regressions, and recent deploys in the change window.`,
+      spec: [
+        `Compare the pages report for the two windows — find which pages lost impressions vs position.`,
+        `Check docs/daily-log.md and data/probes/ for regressions in the window.`,
+        `Cross-reference deploy dates (git log in the site repo) against the drop start.`,
+        `The impact figure is a capped estimate of monthly traffic that recovering this drop would return — it ranks the card, it is not a forecast.`,
+      ],
+      // Every other rule emits recoverable clicks per month; this one starts
+      // from sessions lost across a 28-day window, so normalize before it can
+      // be compared. Discounted because an investigation is not a fix, and
+      // capped: an unbounded loss on effort S would pin this card to the top
+      // of the queue until the traffic came back on its own.
+      impact: Math.min(60, Math.max(1, Math.round(((t.prior - t.recent) / 28) * 30 * 0.3))),
+      effort: "S",
+      tag: "trend",
+      source: "rule",
+    }];
+  }
+  return [];
+}
+
+function metadataActions(site: SiteCfg): Action[] {
+  const audit = data.metadataAudit();
+  const findings = audit?.sites[site.host] ?? audit?.sites[site.gscHost] ?? [];
+  const watch = SHIPPED_WATCH();
+  return findings.slice(0, 5).map((f) => {
+    const pagePath = f.page.replace(/^https?:\/\/[^/]+/, "") || "/";
+    const monthly = Math.max(1, Math.round(f.missed_clicks_window / 3)); // audit window is 90d
+    const watching = watch[f.page];
+    return {
+      id: gid("metadata", f.page),
+      host: site.host,
+      title: `Metadata fix: ${pagePath}`,
+      kind: "Title/meta rewrite — audit finding",
+      why: `${f.imps.toLocaleString()} impressions in 90d; issues: ${f.issues.join("; ")}`,
+      how: `Rewrite the title to carry the ranking-query language and the description as a ~150-char direct answer; respect the ~60-char title budget.`,
+      spec: [
+        `Page: ${f.page}`,
+        `Current title: "${f.title}"`,
+        f.description ? `Current description: "${f.description}"` : "Current description: (none)",
+        `Top queries: ${f.top_queries.map((q) => `“${q.q}” (${q.imps} imps, pos ${q.pos}, ${(100 * q.ctr).toFixed(1)}% CTR)`).join(" · ")}`,
+        ...f.issues.map((i) => `Issue: ${i}`),
+        `Success: CTR on the listed queries reaches ≥ half of position-expected within 28 days. Freeze the title for those 28 days.`,
+      ],
+      impact: monthly,
+      effort: "S" as Effort,
+      tag: "metadata",
+      source: "rule" as const,
+      ...(watching ? { watching } : {}),
+    };
+  });
+}
+
+export function actionsFor(site: SiteCfg): Action[] {
+  const metaActions = metadataActions(site);
+  const metaPages = new Set(metaActions.map((a) => a.spec[0]?.replace("Page: ", "")));
+  const generated = [
+    ...metaActions,
+    ...ctrGapActions(site).filter((a) => !metaPages.has(a.spec[0]?.replace("Page: ", ""))),
+    ...strikingActions(site),
+    ...probeActions(site),
+    ...engagementActions(site),
+    ...trendActions(site),
+  ];
+  const backlog = BACKLOG().filter((b) => b.host === site.host);
+  return [...generated, ...backlog].sort((a, b) => score(b) - score(a));
+}
+
+export function allActions(): Action[] {
+  const sites = SITES();
+  const known = new Set(sites.map((s) => s.host));
+  // Backlog items for hosts no longer in the config still deserve a place.
+  const orphans = BACKLOG().filter((b) => !known.has(b.host));
+  return [...sites.flatMap((s) => actionsFor(s)), ...orphans].sort((a, b) => score(b) - score(a));
+}
+
+export function actionById(id: string): Action | undefined {
+  return allActions().find((a) => a.id === id);
+}

package/src/backlog.ts

@@ -0,0 +1,197 @@
+/**
+ * The curated queue: config/backlog.json.
+ *
+ * { actions: Action[], shippedWatch: { [pageUrl]: note } }
+ *
+ * Why this is hot-reloaded: a static import binds once for the life of the
+ * process. Everything in data.ts is re-read from disk per call, so a
+ * long-lived reader (the stdio MCP server, spawned once by its client and
+ * left running for days) would look healthy — fresh probes, fresh GSC —
+ * while serving a queue frozen at startup. Re-reading on change keeps the
+ * dashboard and the MCP server honest.
+ *
+ * watchFile (stat polling) rather than watch (inode): editors save by
+ * writing a new file and renaming over the old one, which detaches an inode
+ * watcher after the first edit. persistent:false so this never holds a CLI
+ * open.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { INSTANCE } from "./config.js";
+
+export type Effort = "S" | "M" | "L";
+
+export interface Action {
+  id: string;
+  host: string;
+  title: string;
+  /** what kind of work this is — "New page", "Meta/template change", "Content rewrite", … */
+  kind: string;
+  /** the data making the case — numbers included */
+  why: string;
+  /** the concrete move */
+  how: string;
+  /** full spec, shown in the detail modal: URL, outline, schema, links, success metric */
+  spec: string[];
+  /** estimated organic clicks/month gained — for ORDERING, not a forecast */
+  impact: number;
+  effort: Effort;
+  tag: string;
+  /** set when a fix already shipped and the data is being watched */
+  watching?: string;
+  /** rule = derived from data each request; backlog = curated in config/backlog.json */
+  source?: "rule" | "backlog" | "proposal";
+}
+
+interface BacklogFile {
+  _comment?: string;
+  actions: Action[];
+  shippedWatch: Record<string, string>;
+}
+
+export const BACKLOG_PATH = path.join(INSTANCE, "config", "backlog.json");
+const PROPOSALS_PATH = path.join(INSTANCE, "data", "opportunity-proposals.json");
+
+export const slug = (s: string) =>
+  s.toLowerCase().replace(/https?:\/\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+
+const EMPTY: BacklogFile = { actions: [], shippedWatch: {} };
+
+const EFFORTS = new Set<Effort>(["S", "M", "L"]);
+
+/** config/backlog.json is edited by hand — that is the documented workflow —
+ *  so it is untrusted input. An effort outside S|M|L used to give the whole
+ *  queue a NaN comparator (score = impact / weight), and V8 then leaves the
+ *  order of every other card arbitrary. Coerce here, the same way
+ *  acceptProposal() already does on the write path. */
+function readBacklog(): BacklogFile {
+  const raw = JSON.parse(fs.readFileSync(BACKLOG_PATH, "utf8")) as Partial<BacklogFile>;
+  const seen = new Map<string, number>();
+  const actions = (raw.actions ?? []).map((a) => {
+    const impact = Number(a.impact);
+    const base = a.id || slug(`${a.host}-${a.title}`);
+    // slug() truncates at 80 chars, so two long titles can collide; a shared
+    // id would make retire() delete both and setWatching() annotate whichever
+    // came first. Suffix duplicates so every id addresses exactly one card.
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return {
+      ...a,
+      id: n === 1 ? base : `${base}-${n}`,
+      spec: a.spec ?? [],
+      impact: Number.isFinite(impact) ? impact : 0,
+      effort: EFFORTS.has(a.effort) ? a.effort : ("M" as Effort),
+      source: "backlog" as const,
+    };
+  });
+  return { _comment: raw._comment, actions, shippedWatch: raw.shippedWatch ?? {} };
+}
+
+let current: BacklogFile = EMPTY;
+let loadedMtime = 0;
+
+function reload(): void {
+  try {
+    current = readBacklog();
+    loadedMtime = fs.statSync(BACKLOG_PATH).mtimeMs;
+  } catch (err) {
+    // A missing file is the normal state of an instance before its first
+    // curated item; only a real problem (a syntax error mid-edit) is worth
+    // reporting, and it must not take down the dashboard or the MCP server.
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") current = EMPTY;
+    else console.error("[backlog] keeping the last good queue:", (err as Error).message);
+  }
+}
+reload();
+
+try {
+  fs.watchFile(BACKLOG_PATH, { interval: 2000, persistent: false }, (curr, prev) => {
+    if (curr.mtimeMs !== prev.mtimeMs) reload();
+  });
+} catch {
+  // A watch-less environment still gets the startup snapshot.
+}
+
+/** Cheap staleness guard for callers between poll ticks (e.g. right after a write). */
+function ensureFresh(): void {
+  try {
+    if (fs.statSync(BACKLOG_PATH).mtimeMs !== loadedMtime) reload();
+  } catch {
+    /* file missing: keep last good */
+  }
+}
+
+export function BACKLOG(): Action[] {
+  ensureFresh();
+  return current.actions;
+}
+
+export function SHIPPED_WATCH(): Record<string, string> {
+  ensureFresh();
+  return current.shippedWatch;
+}
+
+// ---------- writes (the dashboard's accept / watch / retire buttons) ----------
+
+function write(file: BacklogFile): void {
+  const out = {
+    ...(file._comment ? { _comment: file._comment } : {}),
+    actions: file.actions.map(({ source: _s, ...a }) => a),
+    shippedWatch: file.shippedWatch,
+  };
+  fs.writeFileSync(BACKLOG_PATH, JSON.stringify(out, null, 2) + "\n");
+  reload();
+}
+
+/** Move proposal #index from data/opportunity-proposals.json into the queue. */
+export function acceptProposal(index: number): Action | null {
+  let scan: { proposals?: Omit<Action, "id">[] } & Record<string, unknown>;
+  try {
+    scan = JSON.parse(fs.readFileSync(PROPOSALS_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+  const proposals = scan.proposals ?? [];
+  const p = proposals[index];
+  if (!p) return null;
+  const file = readBacklog();
+  const base = slug(`${p.host}-${p.title}`);
+  let id = base;
+  for (let n = 2; file.actions.some((a) => a.id === id); n++) id = `${base}-${n}`;
+  const action: Action = {
+    id,
+    host: p.host,
+    title: p.title,
+    kind: p.kind || "Proposed by the opportunity scan",
+    why: p.why || "",
+    how: p.how || "",
+    spec: p.spec ?? [],
+    impact: Number(p.impact) || 0,
+    effort: (["S", "M", "L"].includes(String(p.effort)) ? p.effort : "M") as Effort,
+    tag: p.tag || "content",
+  };
+  file.actions.push(action);
+  write(file);
+  proposals.splice(index, 1);
+  fs.writeFileSync(PROPOSALS_PATH, JSON.stringify({ ...scan, proposals }, null, 1) + "\n");
+  return action;
+}
+
+export function setWatching(id: string, note: string): boolean {
+  const file = readBacklog();
+  const a = file.actions.find((x) => x.id === id);
+  if (!a) return false;
+  const stamp = new Date().toISOString().slice(0, 10);
+  a.watching = note.trim() ? `${stamp}: ${note.trim()}` : `${stamp}: shipped — watching the data`;
+  write(file);
+  return true;
+}
+
+export function retire(id: string): boolean {
+  const file = readBacklog();
+  const before = file.actions.length;
+  file.actions = file.actions.filter((x) => x.id !== id);
+  if (file.actions.length === before) return false;
+  write(file);
+  return true;
+}

package/src/config.ts

@@ -0,0 +1,220 @@
+/**
+ * Configuration: one JSON file drives everything.
+ *
+ * n-seo.config.json (or $N_SEO_CONFIG) is read by BOTH this app and
+ * every Python script (ingest/seo_config.py). One site list, one module
+ * switchboard, one auth block — adding a site here adds it to every pull,
+ * probe, audit and page. The example file documents every field.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { execFileSync } from "node:child_process";
+
+/** The engine checkout: code, public assets, engine docs. */
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+/** The instance: one user's config, queue, content and data. Defaults to the
+ *  engine checkout ("in-place" mode) so a plain clone works unchanged; set
+ *  N_SEO_INSTANCE to keep them apart so upgrading the engine is a git pull. */
+export const INSTANCE = process.env.N_SEO_INSTANCE
+  ? path.resolve(process.env.N_SEO_INSTANCE)
+  : ROOT;
+export const CONFIG_PATH = process.env.N_SEO_CONFIG
+  ? path.resolve(process.env.N_SEO_CONFIG)
+  : path.join(INSTANCE, "n-seo.config.json");
+export const EXAMPLE_CONFIG_PATH = path.join(ROOT, "n-seo.config.example.json");
+
+export const ENGINE_VERSION: string = (() => {
+  try {
+    return (JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8")) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+export interface EngineInfo {
+  version: string;
+  commit: string | null;
+  root: string;
+  instance: string;
+  mode: "in-place" | "instance";
+}
+
+/** What is running: engine version + commit, where the engine and the
+ *  instance live. Shown on Settings, by `n-seo version` and the MCP tool. */
+export function engineInfo(): EngineInfo {
+  let commit: string | null = null;
+  try {
+    commit = execFileSync("git", ["-C", ROOT, "rev-parse", "--short", "HEAD"], { stdio: ["ignore", "pipe", "ignore"] })
+      .toString().trim() || null;
+  } catch {
+    commit = null;
+  }
+  return { version: ENGINE_VERSION, commit, root: ROOT, instance: INSTANCE, mode: INSTANCE === ROOT ? "in-place" : "instance" };
+}
+
+export interface SiteCfg {
+  /** canonical hostname — the URL slug in this app and the key in data/ga4/<host>/ */
+  host: string;
+  label: string;
+  /** Search Console property: "sc-domain:example.com" or "https://www.example.com/" */
+  gscProperty?: string;
+  /** hostname to filter GSC page URLs by (a domain property covers subdomains) */
+  gscHost: string;
+  /** numeric GA4 property id, e.g. "123456789" */
+  ga4Property?: string;
+  /** regex (case-insensitive) matching branded queries, for the branded/generic split */
+  brand?: string;
+  repo?: string;
+  hosting?: string;
+}
+
+export interface ModuleCfg {
+  enabled: boolean;
+  [k: string]: unknown;
+}
+
+export interface Hooks {
+  /** shell commands run in the instance dir before the first step */
+  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"] } */
+  afterStep: Record<string, string[]>;
+}
+
+export interface Config {
+  name: string;
+  port: number;
+  google: {
+    /** `metadata` is the GCE / Cloud Run / GKE runtime service account: no
+     *  key file anywhere. See docs/SETUP-GOOGLE.md. */
+    auth: "service-account-key" | "gcloud-impersonate" | "gcloud-user" | "metadata";
+    serviceAccountKey?: string;
+    impersonate?: string;
+  };
+  sites: SiteCfg[];
+  watchPages: string[];
+  conversions?: { site: string; events: string[]; sourceDimension?: string };
+  participation?: { expertise?: string };
+  modules: Record<string, ModuleCfg>;
+  /** extra Search Console properties pulled into data/gsc/<slug>/ but not shown as sites */
+  gscExtraProperties: string[];
+  hooks: Hooks;
+}
+
+/** Per-module defaults, so a half-written block cannot make a step guess.
+ *  Mirrors MODULE_DEFAULTS in ingest/seo_config.py. */
+export const MODULE_DEFAULTS: Record<string, Record<string, unknown>> = {
+  staticExport: { signOutUrl: "", signOutLabel: "Sign out" },
+  publish: { target: "gcs", destination: "", command: "", delete: false, dryRun: false, env: {} },
+};
+
+export const MODULE_INFO: { key: string; title: string; blurb: string; needs?: string }[] = [
+  { key: "indexStatus", title: "Index coverage sweep", blurb: "Ask Search Console's URL Inspection API whether each sitemap URL is actually indexed. ~1 call per URL, 2,000/day quota per property." },
+  { key: "metadataAudit", title: "Metadata audit", blurb: "Fetch each ranking page's live title/description and judge them against the queries it ranks for." },
+  { key: "opportunityScan", title: "Opportunity scan", blurb: "Refresh the 84-day trend analysis and detect rising queries no queue item covers. With the LLM module on, also drafts proposals and verdicts." },
+  { key: "llm", title: "LLM inference", blurb: "Drafts briefings and proposals, either through a local command or an HTTP endpoint. Nothing is auto-applied — output lands as proposals you accept or ignore.", needs: "a CLI that reads a prompt on stdin, or an `http` block with an API key (the only option on a server)" },
+  { key: "hackerNews", title: "Hacker News digest", blurb: "Find fresh HN threads in your expertise areas and brief you on each. Briefings only — no comment text is ever generated.", needs: "your HN username (to mark threads you already joined)" },
+  { key: "reddit", title: "Reddit digest", blurb: "Same idea for subreddits. Reddit blocks anonymous API reads, so this needs a free 'script' app's credentials in .env.", needs: "REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET" },
+  { key: "indexNow", title: "IndexNow", blurb: "Generate a key and ping Bing/Copilot/Yandex with changed URLs on publish. Free and instant; does nothing for Google." },
+  { key: "staticExport", title: "Static export", blurb: "Snapshot the dashboard into site/ as static HTML after each daily run, for hosting a read-only mirror behind your own auth. `signOutUrl` adds a sign-out link to every exported page." },
+  { key: "publish", title: "Publish the mirror", blurb: "Copy site/ to a bucket, an object store or a box over ssh after the export — a real pipeline step, so it is logged and retried like the rest. `dryRun` prints the command without running it, which is how you rehearse a cutover.", needs: "gcloud, aws or rsync on PATH, depending on the target" },
+  { key: "gitAutoCommit", title: "Git auto-commit", blurb: "Commit the daily log and export after each run (and push if a remote is set)." },
+  { key: "notifications", title: "Desktop notifications", blurb: "macOS notification when a daily step fails (osascript)." },
+];
+
+function readJson<T>(p: string): T {
+  return JSON.parse(fs.readFileSync(p, "utf8")) as T;
+}
+
+/** Fill in defaults so the rest of the app can assume the shape. */
+function normalize(raw: Partial<Config>): Config {
+  const modules: Record<string, ModuleCfg> = {};
+  for (const m of MODULE_INFO) modules[m.key] = { enabled: false, ...(MODULE_DEFAULTS[m.key] ?? {}), ...(raw.modules?.[m.key] ?? {}) };
+  for (const [k, v] of Object.entries(raw.modules ?? {})) if (!modules[k]) modules[k] = { ...v, enabled: !!v?.enabled };
+  const sites = (raw.sites ?? []).map((s) => ({
+    ...s,
+    label: s.label || s.host,
+    gscHost: s.gscHost || s.host,
+    gscProperty: s.gscProperty || undefined,
+    ga4Property: s.ga4Property || undefined,
+    brand: s.brand || undefined,
+  }));
+  const strList = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && x.trim() !== "") : []);
+  const rawHooks = (raw.hooks ?? {}) as Partial<Record<string, unknown>>;
+  const afterStep: Record<string, string[]> = {};
+  for (const [k, v] of Object.entries((rawHooks.afterStep as Record<string, unknown>) ?? {})) afterStep[k] = strList(v);
+  return {
+    name: raw.name || "n-seo",
+    port: Number(process.env.SEO_PORT ?? raw.port ?? 4600),
+    google: { ...(raw.google ?? {}), auth: raw.google?.auth || "service-account-key" } as Config["google"],
+    sites,
+    watchPages: raw.watchPages ?? [],
+    conversions: raw.conversions?.site ? raw.conversions : undefined,
+    participation: raw.participation,
+    modules,
+    gscExtraProperties: strList(raw.gscExtraProperties),
+    hooks: { beforeRun: strList(rawHooks.beforeRun), afterRun: strList(rawHooks.afterRun), afterStep },
+  };
+}
+
+/** One KEY=value from the instance's .env (quotes stripped). */
+export function dotEnv(key: string): string | undefined {
+  try {
+    for (const line of fs.readFileSync(path.join(INSTANCE, ".env"), "utf8").split("\n")) {
+      const t = line.trim();
+      if (t.startsWith(`${key}=`)) return t.slice(key.length + 1).trim().replace(/^["']|["']$/g, "") || undefined;
+    }
+  } catch {
+    /* no .env */
+  }
+  return undefined;
+}
+
+/** True when the user has not created their own config yet — the app then
+ *  runs on the example so the UI can explain what to do instead of crashing. */
+export let USING_EXAMPLE_CONFIG = !fs.existsSync(CONFIG_PATH);
+
+export function loadConfig(): Config {
+  USING_EXAMPLE_CONFIG = !fs.existsSync(CONFIG_PATH);
+  const p = USING_EXAMPLE_CONFIG ? EXAMPLE_CONFIG_PATH : CONFIG_PATH;
+  return normalize(readJson<Partial<Config>>(p));
+}
+
+/** Rewrite the config file, keeping unknown keys. Creates it from the example
+ *  on first save (that is how the Settings page bootstraps a new install). */
+export function saveConfig(mutate: (raw: Record<string, unknown>) => void): Config {
+  const src = fs.existsSync(CONFIG_PATH) ? CONFIG_PATH : EXAMPLE_CONFIG_PATH;
+  const raw = readJson<Record<string, unknown>>(src);
+  mutate(raw);
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(raw, null, 2) + "\n");
+  return loadConfig();
+}
+
+/** Live view: re-read on every access so a hand edit shows up without a
+ *  restart (the file is tiny; the cost is nothing next to the data reads). */
+export const config = (): Config => loadConfig();
+export const SITES = (): SiteCfg[] => loadConfig().sites;
+export const PORT = loadConfig().port;
+
+/** data/gsc/<slug>/ — must match ingest/seo_config.py gsc_slug(). */
+export function gscSlug(property: string): string {
+  return property
+    .replace(/^sc-domain:/, "")
+    .replace(/^https?:\/\//, "")
+    .replace(/\/+$/, "")
+    .replace(/\//g, "_");
+}
+
+/** The data/gsc/ directory for a property. A url-prefix property
+ *  ("https://example.com/") would slug to the same name as the domain
+ *  property ("sc-domain:example.com"), so it gets a "-urlprefix" suffix.
+ *  Must match ingest/seo_config.py gsc_data_slug(). */
+export function gscDataSlug(property: string): string {
+  return /^https?:\/\//i.test(property) ? gscSlug(property) + "-urlprefix" : gscSlug(property);
+}
+
+export const siteByHost = (host: string): SiteCfg | undefined =>
+  SITES().find((s) => s.host === host || s.gscHost === host);