n-seo 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n-seo",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Agentic, local-first SEO / AEO / GEO control plane: pulls Search Console + GA4, probes your sites, and ranks the next moves. Your LLM writes the proposals; your coding agent works the queue over MCP.",
   "license": "MIT",
   "author": "En Dash Consulting (https://endash.us)",
@@ -44,6 +44,7 @@
     "ingest/",
     "ops/",
     "probes/",
+    "profiles/",
     "public/",
     "n-seo.config.example.json",
     ".env.example",

package/profiles/aggressive/n-seo.profile.json

@@ -0,0 +1,15 @@
+{
+  "name": "Aggressive",
+  "description": "For a large site with traffic to spare, where the cost of missing an opportunity beats the cost of a wasted afternoon. A wider striking-distance band, a lower impression floor, and a longer queue. Keeps the 28-day freeze: that one is not a preference, it is how Google reads title churn.",
+  "version": "1.0.0",
+  "operatingRules": {
+    "metadataChangesPerWeek": 15
+  },
+  "rules": {
+    "strikingDistance": { "minPosition": 4, "maxPosition": 20, "minImpressions": 5, "maxRows": 25 },
+    "ctrGap": { "minImpressions": 15, "belowExpectedRatio": 0.65 },
+    "engagement": { "minSessions": 15, "maxCards": 6 },
+    "trafficDrop": { "minPriorSessions": 25, "dropRatio": 0.85 },
+    "metadata": { "maxFindings": 10 }
+  }
+}

package/profiles/default/n-seo.profile.json

@@ -0,0 +1,45 @@
+{
+  "name": "n-seo default",
+  "description": "The model n-seo ships with. Evidence before advice, a 28-day freeze after any metadata change, roughly eight of those a week, and decisions on the trailing 90 days. Every value here is the engine default, written out so you can see what a profile controls. It sets no priorities: an out-of-the-box queue should be ordered by the data alone.",
+  "version": "1.0.0",
+  "operatingRules": {
+    "titleFreezeDays": 28,
+    "metadataChangesPerWeek": 8,
+    "decisionWindowDays": 90,
+    "historyMonths": 16
+  },
+  "rules": {
+    "effortWeight": {
+      "S": 1,
+      "M": 2.5,
+      "L": 5
+    },
+    "strikingDistance": {
+      "minPosition": 5,
+      "maxPosition": 15,
+      "minImpressions": 10,
+      "maxRows": 12,
+      "impactPerImpression": 0.06
+    },
+    "ctrGap": {
+      "minImpressions": 30,
+      "belowExpectedRatio": 0.5
+    },
+    "engagement": {
+      "minSessions": 30,
+      "maxEngagement": 0.25,
+      "maxCards": 3
+    },
+    "trafficDrop": {
+      "minPriorSessions": 50,
+      "dropRatio": 0.75
+    },
+    "probe": {
+      "minVisibleTextBytes": 500
+    },
+    "metadata": {
+      "maxFindings": 5
+    },
+    "priorities": []
+  }
+}

package/profiles/patient/n-seo.profile.json

@@ -0,0 +1,16 @@
+{
+  "name": "Patient",
+  "description": "For a site with low traffic, a long sales cycle, or an owner who would rather ship three good changes a month than thirty. Longer freeze, smaller batches, a higher bar before anything is called a problem, and a shorter queue so the list stays readable.",
+  "version": "1.0.0",
+  "operatingRules": {
+    "titleFreezeDays": 56,
+    "metadataChangesPerWeek": 3
+  },
+  "rules": {
+    "strikingDistance": { "minImpressions": 40, "maxRows": 6 },
+    "ctrGap": { "minImpressions": 100, "belowExpectedRatio": 0.4 },
+    "engagement": { "minSessions": 100, "maxCards": 2 },
+    "trafficDrop": { "minPriorSessions": 150, "dropRatio": 0.6 },
+    "metadata": { "maxFindings": 3 }
+  }
+}

package/public/styles.css

@@ -582,7 +582,28 @@ footer .foot-upd a { color: inherit; text-decoration: underline; }
 .s-help { margin: 0; font-size: 0.75rem; color: var(--muted); }
 .s-field { display: flex; flex-direction: column; gap: 4px; font-size: 0.78rem; font-weight: 600; color: var(--muted); margin-top: 4px; flex: 1; }
 .s-field small { font-weight: 500; }
-.s-field input[type="text"], .s-field textarea {
+.s-field input[type="text"], .prio-notes { list-style: none; margin: 8px 0 0; padding: 8px 12px; background: var(--warn-soft); border-radius: 8px; }
+.prio-notes li { font-size: 0.78rem; color: var(--warn); line-height: 1.5; }
+
+.prof-princ { list-style: none; margin: 6px 0 0; padding: 0; display: flex; flex-direction: column; gap: 5px; font-size: 0.78rem; color: var(--muted); }
+.prof-princ .chip { font-size: 0.62rem; }
+.princ { margin: 14px 0 0; }
+.princ-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 12px; padding: 12px 16px 16px; }
+.princ-item { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; }
+.princ-item.hard { border-color: var(--bad-soft); }
+.princ-h { display: flex; align-items: baseline; gap: 7px; font-size: 0.86rem; margin-bottom: 5px; }
+/* .chip ellipsizes at 34ch, and as a flex item it shrinks below that —
+   which turned "hard" into "h…". It is a two-word label; never shrink it. */
+.princ-h .chip { flex: none; }
+.princ-item p { margin: 0; font-size: 0.82rem; color: var(--muted); line-height: 1.55; }
+
+.prof-diff { list-style: none; margin: 6px 0 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
+.prof-diff li { display: flex; align-items: baseline; gap: 6px; flex-wrap: wrap; font-size: 0.76rem; }
+.prof-diff .mono { flex: 1 1 100%; color: var(--muted); }
+.prof-was { font-family: var(--mono); color: var(--muted); text-decoration: line-through; }
+.prof-now { font-family: var(--mono); font-weight: 700; color: var(--accent); }
+
+.s-field textarea {
   font: inherit; font-size: 0.84rem; color: var(--ink); background: var(--panel);
   border: 1px solid var(--line); border-radius: 8px; padding: 7px 10px; width: 100%; font-weight: 400;
 }

package/src/actions.ts

@@ -4,22 +4,27 @@
  *  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 { SITES, config, type SiteCfg, type Priority } 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 };
+/** Read per call, not captured at import: the config is a live view, so a
+ *  profile change or a hand edit takes effect without a restart. */
+const rules = () => config().rules;
 
 /** 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);
+export const score = (a: Action) => {
+  const w = rules().effortWeight;
+  return (Number.isFinite(a.impact) ? a.impact : 0) / (w[a.effort] ?? w.M);
+};
 
-const WINDOW_MONTHS = 3; // decision window = trailing 90 days
+/** The decision window in months, from operatingRules.decisionWindowDays. */
+const windowMonths = () => Math.max(1, config().operatingRules.decisionWindowDays / 30);
 
 const pathOf = (url: string): string => "/" + url.split("/").slice(3).join("/");
 const gid = (tag: string, page: string) => `gen-${tag}-${slug(page) || "root"}`;
@@ -45,7 +50,7 @@ function ctrGapActions(site: SiteCfg): Action[] {
     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 missed = qs.reduce((s, q) => s + (q.impressions / windowMonths()) * (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 {
@@ -73,7 +78,8 @@ function ctrGapActions(site: SiteCfg): Action[] {
 }
 
 function strikingActions(site: SiteCfg): Action[] {
-  const rows = data.strikingDistance(site).slice(0, 12);
+  const r = rules().strikingDistance;
+  const rows = data.strikingDistance(site).slice(0, r.maxRows);
   if (!rows.length) return [];
   const watch = SHIPPED_WATCH();
   const pageFor = topPageForQueries(site);
@@ -84,7 +90,7 @@ function strikingActions(site: SiteCfg): Action[] {
   }
   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 impact = Math.round((imps / windowMonths()) * r.impactPerImpression);
     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 {
@@ -127,17 +133,18 @@ function probeActions(site: SiteCfg): Action[] {
   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)
+  if ((p.homepage.visible_text_bytes ?? 0) < rules().probe.minVisibleTextBytes && 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 e = rules().engagement;
   const watch = SHIPPED_WATCH();
   return data
     .landingPages(site)
-    .filter((l) => l.sessions >= 30 && l.engagement < 0.25 && l.page !== "(not set)")
-    .slice(0, 3)
+    .filter((l) => l.sessions >= e.minSessions && l.engagement < e.maxEngagement && l.page !== "(not set)")
+    .slice(0, e.maxCards)
     .map((l) => {
       const url = `https://${site.gscHost}${l.page}`;
       // GA landing paths carry no trailing slash; shippedWatch keys may have one
@@ -167,7 +174,8 @@ function engagementActions(site: SiteCfg): Action[] {
 
 function trendActions(site: SiteCfg): Action[] {
   const t = data.sessionTrend(site);
-  if (t.prior >= 50 && t.recent < t.prior * 0.75) {
+  const d = rules().trafficDrop;
+  if (t.prior >= d.minPriorSessions && t.recent < t.prior * d.dropRatio) {
     return [{
       id: `gen-trend-${slug(site.host)}`,
       host: site.host,
@@ -199,7 +207,7 @@ 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) => {
+  return findings.slice(0, rules().metadata.maxFindings).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];
@@ -242,12 +250,80 @@ export function actionsFor(site: SiteCfg): Action[] {
   return [...generated, ...backlog].sort((a, b) => score(b) - score(a));
 }
 
+/** The page a card is about, if it names one. Rule-derived cards put
+ *  "Page: <url>" first in their spec; hygiene and trend cards are about a
+ *  whole site and have no path to match. */
+function pageOf(a: Action): string | null {
+  const line = a.spec?.find((l) => l.startsWith("Page: "));
+  if (!line) return null;
+  const url = line.slice("Page: ".length).trim();
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url.startsWith("/") ? url : null;
+  }
+}
+
+function matches(p: Priority, a: Action): boolean {
+  const w = p.when ?? {};
+  if (w.host && w.host !== a.host) return false;
+  if (w.tag && w.tag !== a.tag) return false;
+  if (w.kind && !a.kind?.toLowerCase().includes(w.kind.toLowerCase())) return false;
+  if (w.pathMatches) {
+    const path = pageOf(a);
+    if (path === null) return false;
+    try {
+      if (!new RegExp(w.pathMatches).test(path)) return false;
+    } catch {
+      // A bad pattern must not silently match everything, and must not take
+      // the queue down either.
+      return false;
+    }
+  }
+  // A priority with no conditions would apply to the whole queue, which is
+  // never what someone means and is a very confusing way to find out.
+  return Object.keys(w).length > 0;
+}
+
+/** Apply the configured priorities: drop, reweight, and always explain.
+ *
+ *  Order is preserved as a pipeline — later priorities see the impact earlier
+ *  ones produced — so two boosts on the same card compound, which is what
+ *  reading them top to bottom implies. */
+export function prioritize(actions: Action[]): Action[] {
+  const priorities = (config().rules.priorities ?? []).filter((p) => p?.why && p?.when);
+  if (!priorities.length) return actions;
+
+  const out: Action[] = [];
+  for (const a of actions) {
+    let card = a;
+    let dropped = false;
+    const notes: string[] = [];
+    for (const p of priorities) {
+      if (!matches(p, card)) continue;
+      if (p.drop) { dropped = true; break; }
+      const by = Number(p.multiply);
+      if (!Number.isFinite(by) || by <= 0 || by === 1) continue;
+      const before = Number.isFinite(card.impact) ? card.impact : 0;
+      card = { ...card, impact: Math.max(0, Math.round(before * by)) };
+      notes.push(`${by > 1 ? "Raised" : "Lowered"} ${before} → ${card.impact}: ${p.why}`);
+    }
+    if (dropped) continue;
+    // The card carries its own adjustment. Ordering you cannot see the reason
+    // for is ordering you cannot argue with.
+    if (notes.length) card = { ...card, spec: [...(card.spec ?? []), ...notes], priorityNotes: notes };
+    out.push(card);
+  }
+  return out;
+}
+
 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));
+  const all = [...sites.flatMap((s) => actionsFor(s)), ...orphans];
+  return prioritize(all).sort((a, b) => score(b) - score(a));
 }
 
 export function actionById(id: string): Action | undefined {

package/src/backlog.ts

@@ -39,6 +39,8 @@ export interface Action {
   tag: string;
   /** set when a fix already shipped and the data is being watched */
   watching?: string;
+  /** why a configured priority raised or lowered this card's impact */
+  priorityNotes?: string[];
   /** rule = derived from data each request; backlog = curated in config/backlog.json */
   source?: "rule" | "backlog" | "proposal";
 }

package/src/config.ts

@@ -9,6 +9,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 
 import { execFileSync } from "node:child_process";
 
@@ -84,6 +85,147 @@ export interface Hooks {
   afterStep: Record<string, string[]>;
 }
 
+
+/** The numbers the action engine ranks by.
+ *
+ *  These were literals scattered through actions.ts and data.ts, which meant
+ *  disagreeing with any of them required editing the engine — and then living
+ *  with the merge every time you upgraded. A practitioner's judgement about
+ *  what counts as striking distance is exactly the thing they should be able
+ *  to change without forking. */
+export interface Rules {
+  /** Impact is divided by this to rank. Higher = the effort costs more. */
+  effortWeight: { S: number; M: number; L: number };
+  strikingDistance: {
+    minPosition: number;
+    maxPosition: number;
+    minImpressions: number;
+    /** How many query rows to consider per site. */
+    maxRows: number;
+    /** Monthly clicks assumed per impression if the query moves into the top 5. */
+    impactPerImpression: number;
+  };
+  ctrGap: {
+    minImpressions: number;
+    /** Flagged when actual CTR is below expected × this. */
+    belowExpectedRatio: number;
+  };
+  engagement: { minSessions: number; maxEngagement: number; maxCards: number };
+  trafficDrop: {
+    minPriorSessions: number;
+    /** Flagged when recent < prior × this. */
+    dropRatio: number;
+  };
+  probe: { minVisibleTextBytes: number };
+  metadata: { maxFindings: number };
+  /** Ordering adjustments. Applied after the rules run, before the sort. */
+  priorities: Priority[];
+}
+
+/** The policy a human follows, as opposed to the numbers a rule sorts by.
+ *
+ *  Read by the dashboard, the daily log and the agent skills, so changing the
+ *  freeze here changes it everywhere it is stated — rather than in six places
+ *  that drift apart. */
+export interface OperatingRules {
+  titleFreezeDays: number;
+  metadataChangesPerWeek: number;
+  /** Decisions ride this window; the long history is for totals only. */
+  decisionWindowDays: number;
+  historyMonths: number;
+}
+
+/** A named bundle of the two above, plus module defaults and skills.
+ *  Resolved from `profile` in the config. See docs/PROFILES.md. */
+export interface Profile {
+  name: string;
+  description?: string;
+  version?: string;
+  operatingRules?: Partial<OperatingRules>;
+  rules?: DeepPartial<Rules>;
+  modules?: Record<string, ModuleCfg>;
+  /** Directory of SKILL.md folders, relative to the profile, copied by `n-seo init`. */
+  skills?: string;
+  /** The parts of a method that are not a number.
+   *
+   *  Building the first real profile is what surfaced this. A practitioner's
+   *  method turned out to be barely distinguishable from ours in thresholds —
+   *  the striking-distance floor never binds once rows are sorted by
+   *  impressions — and almost entirely distinguishable in judgement: what to
+   *  optimise for, what needs a human's approval, what never to automate.
+   *  None of that is expressible as a threshold, and a profile that cannot
+   *  carry it is not a method, just a settings file.
+   *
+   *  Shown on the dashboard and written into the instance's CLAUDE.md, so the
+   *  owner and their agent read the same rules. */
+  principles?: ProfilePrinciple[];
+}
+
+export interface ProfilePrinciple {
+  title: string;
+  body: string;
+  /** `hard` rules are constraints an agent must not cross; `guide` is
+   *  judgement it should apply. The dashboard shows them apart because they
+   *  are different kinds of claim. */
+  kind?: "hard" | "guide";
+}
+
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
+
+export const DEFAULT_RULES: Rules = {
+  effortWeight: { S: 1, M: 2.5, L: 5 },
+  strikingDistance: { minPosition: 5, maxPosition: 15, minImpressions: 10, maxRows: 12, impactPerImpression: 0.06 },
+  ctrGap: { minImpressions: 30, belowExpectedRatio: 0.5 },
+  engagement: { minSessions: 30, maxEngagement: 0.25, maxCards: 3 },
+  trafficDrop: { minPriorSessions: 50, dropRatio: 0.75 },
+  probe: { minVisibleTextBytes: 500 },
+  metadata: { maxFindings: 5 },
+  priorities: [],
+};
+
+export const DEFAULT_OPERATING_RULES: OperatingRules = {
+  titleFreezeDays: 28,
+  metadataChangesPerWeek: 8,
+  decisionWindowDays: 90,
+  historyMonths: 16,
+};
+
+/** A declarative adjustment to the queue's ordering.
+ *
+ *  This is n-seo's answer to "custom rules", and it is deliberately not a
+ *  plugin API. Building the first real profile showed what a practitioner
+ *  actually wants to express: "prefer pages that lead somewhere", "stop
+ *  showing me /legal". That is matching and weighting, not arbitrary code —
+ *  and a profile that ships code means installing someone's method runs their
+ *  program next to your Search Console credentials.
+ *
+ *  Two hard constraints on the design:
+ *
+ *    - A priority may reorder or hide, never invent. It cannot fabricate a
+ *      card, so it cannot manufacture evidence.
+ *    - Every card it touches says so, and says why. A queue that silently
+ *      reorders itself is a queue whose order you cannot trust, and the whole
+ *      product rests on showing its working. */
+export interface Priority {
+  /** Shown on every card this touches. Required: an unexplained boost is the
+   *  one thing this must never be. */
+  why: string;
+  when: {
+    /** Exact host, e.g. "example.com". */
+    host?: string;
+    /** Regular expression against the URL path of the page the card is about. */
+    pathMatches?: string;
+    /** Rule tag: metadata, striking, ctr-gap, engagement, hygiene, trend. */
+    tag?: string;
+    /** Substring of the card's `kind`, case-insensitive. */
+    kind?: string;
+  };
+  /** Multiply the impact used for ordering. 1.5 = half again; 0.5 = half. */
+  multiply?: number;
+  /** Remove the card entirely. For pages you have decided not to work on. */
+  drop?: boolean;
+}
+
 export interface Config {
   name: string;
   port: number;
@@ -102,6 +244,10 @@ export interface Config {
   /** extra Search Console properties pulled into data/gsc/<slug>/ but not shown as sites */
   gscExtraProperties: string[];
   hooks: Hooks;
+  /** Built-in name ("default"), a path, or an installed package. */
+  profile?: string;
+  rules: Rules;
+  operatingRules: OperatingRules;
 }
 
 /** Per-module defaults, so a half-written block cannot make a step guess.
@@ -133,10 +279,82 @@ function readJson<T>(p: string): T {
 }
 
 /** Fill in defaults so the rest of the app can assume the shape. */
+
+/** Where a profile spec resolves to, or null if it does not.
+ *
+ *  Three forms, in the order they are tried:
+ *    "default"            a profile shipped with the engine
+ *    "./x" or "/x"        a directory in or near the instance
+ *    "n-seo-profile-acme" an installed package
+ *
+ *  Resolution is deliberately explicit rather than clever: a profile that
+ *  cannot be found must be an error the owner sees, never a silent fallback
+ *  to our defaults. Someone running a client's portfolio on their agency's
+ *  method should not discover it quietly stopped applying. */
+export function resolveProfileDir(spec: string): string | null {
+  const builtin = path.join(ROOT, "profiles", spec);
+  if (!spec.includes("/") && !spec.includes("\\") && fs.existsSync(path.join(builtin, PROFILE_FILE))) return builtin;
+
+  const asPath = path.isAbsolute(spec) ? spec : path.resolve(INSTANCE, spec);
+  if (fs.existsSync(path.join(asPath, PROFILE_FILE))) return asPath;
+
+  try {
+    const req = createRequire(path.join(INSTANCE, "package.json"));
+    return path.dirname(req.resolve(`${spec}/${PROFILE_FILE}`));
+  } catch {
+    return null;
+  }
+}
+
+export const PROFILE_FILE = "n-seo.profile.json";
+
+/** The resolved profile, or null when none is configured. Throws when one is
+ *  configured and cannot be found — see resolveProfileDir. */
+export function loadProfile(spec: string | undefined): { profile: Profile; dir: string } | null {
+  if (!spec) return null;
+  const dir = resolveProfileDir(spec);
+  if (!dir) {
+    throw new Error(
+      `profile "${spec}" could not be resolved.\n` +
+      `  tried: a profile shipped with the engine (${path.join(ROOT, "profiles", spec)}),\n` +
+      `         a directory relative to the instance (${path.resolve(INSTANCE, spec)}),\n` +
+      `         and an installed package.\n` +
+      `  install it, fix the path, or remove "profile" from the config.`,
+    );
+  }
+  const profile = readJson<Profile>(path.join(dir, PROFILE_FILE));
+  return { profile: { ...profile, name: profile.name || spec }, dir };
+}
+
+/** Recursive merge for the plain-object config trees. Later wins; undefined
+ *  never overwrites, so a profile may set one threshold without restating the
+ *  block it lives in. */
+function merge<T>(base: T, ...layers: unknown[]): T {
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const layer of layers) {
+    if (!layer || typeof layer !== "object") continue;
+    for (const [k, v] of Object.entries(layer as Record<string, unknown>)) {
+      if (v === undefined) continue;
+      const cur = out[k];
+      out[k] = cur && typeof cur === "object" && !Array.isArray(cur) && v && typeof v === "object" && !Array.isArray(v)
+        ? merge(cur, v)
+        : v;
+    }
+  }
+  return out as T;
+}
+
 function normalize(raw: Partial<Config>): Config {
+  const loaded = loadProfile(raw.profile);
+  const fromProfile = loaded?.profile;
+
   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 };
+  for (const m of MODULE_INFO) {
+    modules[m.key] = { enabled: false, ...(MODULE_DEFAULTS[m.key] ?? {}), ...(fromProfile?.modules?.[m.key] ?? {}), ...(raw.modules?.[m.key] ?? {}) };
+  }
+  for (const [k, v] of Object.entries({ ...(fromProfile?.modules ?? {}), ...(raw.modules ?? {}) })) {
+    if (!modules[k]) modules[k] = { ...v, enabled: !!v?.enabled };
+  }
   const sites = (raw.sites ?? []).map((s) => ({
     ...s,
     label: s.label || s.host,
@@ -160,6 +378,15 @@ function normalize(raw: Partial<Config>): Config {
     modules,
     gscExtraProperties: strList(raw.gscExtraProperties),
     hooks: { beforeRun: strList(rawHooks.beforeRun), afterRun: strList(rawHooks.afterRun), afterStep },
+    profile: raw.profile,
+    // engine defaults <- profile <- this instance. The instance always wins,
+    // so a client can always see, and override, where they depart from the
+    // method they installed.
+    // `merge` replaces arrays rather than concatenating, so an instance that
+    // sets `priorities` replaces the profile's outright. Appending would make
+    // a profile's priority impossible to remove without forking it.
+    rules: merge(DEFAULT_RULES, fromProfile?.rules, raw.rules),
+    operatingRules: merge(DEFAULT_OPERATING_RULES, fromProfile?.operatingRules, raw.operatingRules),
   };
 }
 

package/src/data.ts

@@ -96,10 +96,14 @@ export function gscSummary(site: SiteCfg): GscSummary {
 }
 
 /** Position 5–15 queries with meaningful impressions — the cheapest ranking wins. */
-export function strikingDistance(site: SiteCfg, minImpressions = 10): GscRow[] {
-  // Recent window: decisions ride the last 90 days, not 16-month history.
+export function strikingDistance(site: SiteCfg, minImpressions?: number): GscRow[] {
+  // Recent window: decisions ride the trailing window, not 16-month history.
+  // The band is a rule, so a practitioner who thinks striking distance is
+  // 4-12 rather than 5-15 changes a config key instead of the engine.
+  const r = config().rules.strikingDistance;
+  const min = minImpressions ?? r.minImpressions;
   return queries(site, true)
-    .filter((r) => r.position >= 5 && r.position <= 15 && r.impressions >= minImpressions)
+    .filter((q) => q.position >= r.minPosition && q.position <= r.maxPosition && q.impressions >= min)
     .sort((a, b) => b.impressions - a.impressions);
 }
 
@@ -114,12 +118,14 @@ export const EXPECTED_CTR: Record<number, number> = {
 };
 
 /** Ranking well but rarely clicked — title/snippet problems. */
-export function ctrGaps(site: SiteCfg, minImpressions = 30): (GscRow & { expected: number })[] {
+export function ctrGaps(site: SiteCfg, minImpressions?: number): (GscRow & { expected: number })[] {
+  const rule = config().rules.ctrGap;
+  const min = minImpressions ?? rule.minImpressions;
   // Recent window: a page fixed last week must stop being accused within 90 days.
   return queries(site, true)
     .flatMap((r) => {
       const expected = EXPECTED_CTR[Math.round(r.position)];
-      return expected && r.impressions >= minImpressions && r.ctr < expected * 0.5
+      return expected && r.impressions >= min && r.ctr < expected * rule.belowExpectedRatio
         ? [{ ...r, expected }]
         : [];
     })

package/src/profile-cli.ts

@@ -0,0 +1,34 @@
+/** `n-seo profile` — what method is running, and where you depart from it. */
+import { profileReport, builtinProfiles } from "./profile-report.js";
+
+const r = profileReport();
+const built = builtinProfiles();
+
+console.log(`profile   ${r.name}${r.version ? ` ${r.version}` : ""}${r.spec ? "" : "  (no profile set)"}`);
+if (r.spec) console.log(`spec      ${r.spec}`);
+if (r.dir) console.log(`from      ${r.dir}`);
+if (r.description) {
+  console.log("");
+  for (const line of r.description.match(/.{1,72}(\s|$)/g) ?? []) console.log(`  ${line.trim()}`);
+}
+
+console.log("");
+if (r.departures.length === 0) {
+  console.log(r.spec
+    ? "this instance changes nothing — it runs the profile as published"
+    : "this instance changes nothing — it runs the engine defaults");
+} else {
+  console.log(`this instance overrides ${r.departures.length} value(s):\n`);
+  const w = Math.max(...r.departures.map((d) => d.key.length));
+  for (const d of r.departures) {
+    console.log(`  ${d.key.padEnd(w)}  ${JSON.stringify(d.inherited)} → ${JSON.stringify(d.instance)}`);
+  }
+}
+
+if (built.length) {
+  console.log(`\nshipped with this engine:`);
+  const w = Math.max(...built.map((b) => b.spec.length));
+  for (const b of built) console.log(`  ${b.spec.padEnd(w)}  ${b.name}`);
+  console.log(`\nset one with "profile": "<name>" in n-seo.config.json, or point it at`);
+  console.log(`a directory or an installed package. See docs/PROFILES.md.`);
+}