n-seo 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,49 @@ uses [Semantic Versioning](https://semver.org/).
 
 Nothing yet.
 
+## [0.5.0] - 2026-09-14
+
+The operating model was ours, hardcoded. Now it is a file you can install.
+
+### Added
+- **Profiles.** One config key — `"profile"` — swaps every threshold and
+  policy the engine uses for someone else's. Resolves a name shipped with the
+  engine, a path, or an installed package, in that order. Three ship:
+  `default` (the engine's own model, written out so you can read what a
+  profile controls), `patient` and `aggressive`.
+- **Three layers, and the instance always wins**: engine defaults, then the
+  profile, then this instance. That is the part that makes a profile usable
+  for client work — a client running their agency's method can always see,
+  and change, exactly where their setup departs from it. `n-seo profile`
+  prints that list; the Settings page shows it beside the profile's name.
+- **A profile that cannot be resolved fails the load**, naming every location
+  tried, rather than falling back to the defaults. Discovering months later
+  that a client's instance quietly stopped applying your method is worse than
+  an error on the morning you typed the name wrong. `doctor` reports it too.
+- **`rules` in config.** Every number the action engine ranks by — the
+  striking-distance band, the impression floors, the CTR ratio, the
+  engagement thresholds, the drop percentage, the effort weights — was a
+  literal in `src/actions.ts` and `src/data.ts`. Disagreeing with any of them
+  meant editing the engine and then living with the merge on every upgrade.
+- **`operatingRules` in config**: the freeze window, the weekly batch size,
+  the decision window, the history length. One place, so changing the freeze
+  changes it everywhere it is stated rather than in six that drift.
+- `docs/PROFILES.md`, and a section on the site for people who do this for a
+  living.
+
+### Decided
+- A profile is data and may not ship executable code. Installing someone's
+  method should not mean running their code on the machine that holds your
+  Search Console credentials. Custom rules — new kinds of card rather than new
+  numbers for existing ones — remain a fork, and the PRD carries the open
+  question.
+
+### Fixed
+- The TypeScript and Python loaders now resolve profiles identically, asserted
+  by a test that runs both against every shipped profile. A dashboard saying
+  the freeze is 28 days while the daily log says 56 would be worse than either
+  number being wrong.
+
 ## [0.4.1] - 2026-09-13
 
 ### Added
@@ -401,7 +444,8 @@ First public release.
   `n-seo upgrade` gate — without changing the reported test counts, and an
   in-place install ran those assertions against the owner's live data.
 
-[Unreleased]: https://github.com/en-dash-consulting/n-seo/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/en-dash-consulting/n-seo/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/en-dash-consulting/n-seo/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/en-dash-consulting/n-seo/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/en-dash-consulting/n-seo/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/en-dash-consulting/n-seo/compare/v0.3.2...v0.3.3

package/README.md

@@ -8,7 +8,7 @@
 
 An agentic, local-first control plane for growing organic traffic to your own
 sites — classic search (SEO), answer engines (AEO) and AI assistants that cite
-sources (GEO) — without paying an agency to read Search Console for you.
+sources (GEO). Your sites, your data, your call.
 
 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,

package/bin/n-seo.mjs

@@ -41,6 +41,7 @@ usage: n-seo <command> [--instance <dir>] [args...]
   check           engine self-test: typecheck + unit tests
   upgrade         update the engine in place, whatever way it was installed;
                   --check reports what is available without changing anything
+  profile         the active profile, and every value this instance overrides
   version         engine version, commit, paths, mode
   help            this text
 
@@ -548,6 +549,7 @@ switch (cmd) {
   case "init":
     code = init(rest.find((a) => !a.startsWith("-")) ?? flag ?? process.cwd(), rest.includes("--force"));
     break;
+  case "profile":
   case "start":
   case "dev":
   case "mcp": {
@@ -558,7 +560,9 @@ switch (cmd) {
       code = missingDeps(cmd, "the engine's dependencies");
       break;
     }
-    const entry = cmd === "mcp" ? "src/mcp-stdio.ts" : "src/server.tsx";
+    const entry = cmd === "mcp" ? "src/mcp-stdio.ts"
+      : cmd === "profile" ? "src/profile-cli.ts"
+      : "src/server.tsx";
     const args = cmd === "dev" ? ["watch", entry] : [entry];
     code = run(process.execPath, [bin, ...args, ...rest], instance);
     break;

package/docs/PRD.md

@@ -10,16 +10,19 @@ check. Status markers: **[shipped]**, **[planned]**, **[idea]**.
 
 n-seo is a local-first control plane for organic growth across one or more
 websites: classic search (SEO), answer engines (AEO) and generative engines
-that cite sources (GEO). It replaces the monthly agency read-out with a loop
+that cite sources (GEO). It replaces the monthly read-out with a loop
 that runs every morning on the owner's machine: pull Search Console and GA4,
 probe the live sites, turn the data into a ranked queue of concrete actions
 with evidence attached, and measure yesterday's changes.
 
 ## Users
 
-- **A site owner or small team** who wants to hone their own SEO practice
-  without paying an agency: developers, indie makers, consultancies, small
-  businesses with a technical person.
+- **A site owner or small team** who wants to run their own search practice
+  and understand it: developers, indie makers, consultancies, small businesses
+  with a technical person. Note that agencies and consultancies are users
+  here, not the thing being displaced — the copy should never imply otherwise,
+  and the tool is as useful to someone doing this for clients as for
+  themselves.
 - **An operator running several sites** (a portfolio, an agency serving its
   own clients) who needs one queue across all of them.
 - **An AI agent** (Claude Code, Claude Desktop, any MCP client) acting for
@@ -136,14 +139,34 @@ a fresh checkout runs.
 - Acceptance: `config/backlog.json` is merged and hot-reloaded without a
   restart, and a syntax error keeps the last good queue.
 
-## Feature: Rule thresholds in config [planned]
-
-Move the numeric thresholds (min impressions, position band, engagement
-floor, drop percentage, effort weights) into an optional `rules` block of
-the config with the current values as defaults.
-
-- Acceptance: every threshold has a documented default and a config
-  override; tests cover an override changing a rule's output.
+## Feature: Profiles — a method you can install [shipped]
+
+n-seo ships one operating model; a practitioner has their own. A **profile**
+packages thresholds, policy numbers and module defaults so a method can be
+published once and installed many times. Full reference: `docs/PROFILES.md`.
+
+- Acceptance: `"profile": "<built-in | path | package>"` resolves in that
+  order, and every value remains overridable by the instance.
+- Acceptance: a profile that cannot be resolved fails the load with a message
+  naming each location tried, rather than falling back to the defaults.
+- Acceptance: `n-seo profile` prints the active profile and every value this
+  instance overrides; the Settings page shows the same, and `doctor` reports
+  an unresolvable profile before the daily run reaches it.
+- Acceptance: the TypeScript and Python loaders resolve every shipped profile
+  to identical numbers, asserted by a test that runs both.
+- Acceptance: `default`, `patient` and `aggressive` ship with the engine, and
+  `default` restates the engine defaults exactly — asserted, so the two cannot
+  drift.
+- Decided: a profile is data only and may not ship executable code. Installing
+  a method should not mean running its author's code on the machine holding
+  your Search Console credentials. Custom *rules* — new kinds of card rather
+  than new numbers — remain a fork, and are the open question.
+
+## Feature: Rule thresholds in config [shipped]
+
+- Acceptance: every threshold the action engine ranks by lives in `rules`,
+  with the engine defaults documented in `src/config.ts` and mirrored in
+  `ingest/seo_config.py`; tests cover an override changing a rule's output.
 
 # Epic: Dashboard [shipped]
 

package/docs/PROFILES.md

@@ -0,0 +1,135 @@
+# Profiles — a method you can install
+
+n-seo ships with an opinionated model: a 28-day freeze after any metadata
+change, roughly eight of those a week, striking distance meaning positions
+5–15, decisions on the trailing 90 days. Those numbers are a position, not a
+law, and if you do this for a living yours are probably different.
+
+A **profile** is that position, packaged. One config key, and every threshold
+and policy the engine uses comes from your profile instead of ours.
+
+```jsonc
+{
+  "profile": "patient",
+  "sites": [ ... ]
+}
+```
+
+## The three layers
+
+```
+engine defaults          what n-seo believes, in src/config.ts
+   ↓  overridden by
+the profile              what you or your agency believes
+   ↓  overridden by
+this instance            what this one client needs
+```
+
+The instance always wins. That matters more than it sounds: a client running
+their agency's profile can always see, and change, exactly where their setup
+departs from it. `n-seo profile` prints that list, and the Settings page shows
+it beside the profile's name.
+
+```
+$ n-seo profile
+profile   Patient 1.0.0
+spec      patient
+from      /opt/n-seo/profiles/patient
+
+this instance overrides 2 value(s):
+
+  operatingRules.titleFreezeDays  56 → 30
+  rules.strikingDistance.maxRows  6 → 9
+```
+
+## What a profile can set
+
+`n-seo.profile.json`, at the root of a directory or a package:
+
+```jsonc
+{
+  "name": "Acme Search",
+  "description": "How we run search for retail clients.",
+  "version": "1.2.0",
+
+  // The policy a human follows.
+  "operatingRules": {
+    "titleFreezeDays": 28,          // hands off a page's metadata this long
+    "metadataChangesPerWeek": 8,    // batch size across the portfolio
+    "decisionWindowDays": 90,       // decisions ride this window
+    "historyMonths": 16             // the long view, for totals only
+  },
+
+  // The numbers the action engine ranks by.
+  "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 }
+  },
+
+  // Module defaults. The instance can still switch any of them.
+  "modules": {
+    "indexNow": { "enabled": true }
+  }
+}
+```
+
+Set only what you disagree with. Anything absent is inherited, so a profile
+that changes one threshold is three lines long.
+
+## Shipped with the engine
+
+| spec | what it is for |
+|---|---|
+| `default` | The engine's own model, written out so you can read what a profile controls. |
+| `patient` | Low traffic, 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. |
+| `aggressive` | A large site with traffic to spare, where missing an opportunity costs more than a wasted afternoon. Wider band, lower floors, longer queue. Keeps the 28-day freeze — that one is not a preference. |
+
+`n-seo profile` lists them.
+
+## Writing your own
+
+A profile is a directory with an `n-seo.profile.json` in it. Three ways to
+point at one:
+
+```jsonc
+"profile": "patient"                  // shipped with the engine
+"profile": "./profiles/acme"          // a path, relative to the instance
+"profile": "n-seo-profile-acme"       // an installed package
+```
+
+To publish one, make it a package whose root holds the file:
+
+```
+n-seo-profile-acme/
+├── package.json
+└── n-seo.profile.json
+```
+
+Then `npm i n-seo-profile-acme` in the instance and name it in the config.
+Versioning the package versions the method, which is the point: "we moved you
+to Acme Search 2.0" is a sentence a client can check.
+
+## When a profile cannot be found
+
+The run fails, loudly, naming every location that was tried. It does **not**
+fall back to the engine defaults. Someone running a client's portfolio on
+their agency's method should never discover it quietly stopped applying —
+a wrong answer you can see beats a plausible one you cannot.
+
+`n-seo doctor` reports the same thing before the daily run gets there.
+
+## What a profile cannot do
+
+It cannot ship executable code. A profile is data: thresholds, policy numbers
+and module defaults. Installing someone's method should not mean running
+their code on the machine that holds your Search Console credentials.
+
+Custom *rules* — new kinds of card, not new numbers for existing ones — are a
+real gap, and the honest answer today is to fork the engine. `docs/PRD.md`
+carries the open question.

package/ingest/seo_config.py

@@ -57,6 +57,62 @@ MODULE_DEFAULTS = {
                 "delete": False, "dryRun": False, "env": {}},
 }
 
+PROFILE_FILE = "n-seo.profile.json"
+
+# Mirrors DEFAULT_RULES / DEFAULT_OPERATING_RULES in src/config.ts. The
+# TypeScript side is where the action engine reads them; Python needs them so
+# the daily log, the digests and doctor state the same numbers the dashboard
+# does, rather than a second set that drifts.
+DEFAULT_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},
+}
+
+DEFAULT_OPERATING_RULES = {
+    "titleFreezeDays": 28,
+    "metadataChangesPerWeek": 8,
+    "decisionWindowDays": 90,
+    "historyMonths": 16,
+}
+
+
+def profile_dir(spec):
+    """Where a profile spec resolves to, or None. Mirrors resolveProfileDir."""
+    if not spec:
+        return None
+    if "/" not in spec and "\\" not in spec:
+        built = ROOT / "profiles" / spec
+        if (built / PROFILE_FILE).exists():
+            return built
+    as_path = Path(spec) if Path(spec).is_absolute() else (INSTANCE / spec)
+    if (as_path / PROFILE_FILE).exists():
+        return as_path.resolve()
+    # An installed package, without importing node: node_modules beside the
+    # instance, then beside the engine.
+    for base in (INSTANCE, ROOT):
+        cand = base / "node_modules" / spec
+        if (cand / PROFILE_FILE).exists():
+            return cand.resolve()
+    return None
+
+
+def _merge(base, over):
+    """Deep merge; `over` wins, and None never overwrites."""
+    out = dict(base)
+    for k, v in (over or {}).items():
+        if v is None:
+            continue
+        cur = out.get(k)
+        out[k] = _merge(cur, v) if isinstance(cur, dict) and isinstance(v, dict) else v
+    return out
+
+
 _cache = None
 
 
@@ -73,9 +129,22 @@ def load(force: bool = False) -> dict:
         return _cache
     path = CONFIG_PATH if CONFIG_PATH.exists() else EXAMPLE_PATH
     raw = json.loads(path.read_text(encoding="utf-8"))
-    modules = {k: {"enabled": False, **MODULE_DEFAULTS.get(k, {})} for k in MODULE_KEYS}
-    for k, v in (raw.get("modules") or {}).items():
-        modules[k] = {"enabled": False, **MODULE_DEFAULTS.get(k, {}), **(v or {})}
+    # engine defaults <- profile <- this instance, for modules and both rule
+    # blocks. The instance always wins.
+    prof = {}
+    pdir = profile_dir(raw.get("profile"))
+    if pdir:
+        try:
+            prof = json.loads((pdir / PROFILE_FILE).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            prof = {}
+
+    pmods = prof.get("modules") or {}
+    modules = {k: {"enabled": False, **MODULE_DEFAULTS.get(k, {}), **(pmods.get(k) or {})}
+               for k in MODULE_KEYS}
+    for k, v in {**pmods, **(raw.get("modules") or {})}.items():
+        modules[k] = {"enabled": False, **MODULE_DEFAULTS.get(k, {}),
+                      **(pmods.get(k) or {}), **((raw.get("modules") or {}).get(k) or {})}
     sites = []
     for s in raw.get("sites") or []:
         if not s.get("host"):
@@ -109,6 +178,10 @@ def load(force: bool = False) -> dict:
         "conversions": conv if conv.get("site") else None,
         "participation": raw.get("participation") or {},
         "modules": modules,
+        "profile": raw.get("profile"),
+        "rules": _merge(_merge(DEFAULT_RULES, prof.get("rules")), raw.get("rules")),
+        "operatingRules": _merge(_merge(DEFAULT_OPERATING_RULES, prof.get("operatingRules")),
+                                 raw.get("operatingRules")),
         "gscExtraProperties": str_list(raw.get("gscExtraProperties")),
         "hooks": hooks,
     }

package/n-seo.config.example.json

@@ -1,5 +1,6 @@
 {
   "name": "My sites",
+  "_profile": "Optional. A method to inherit: a name shipped with the engine (default, patient, aggressive), a path, or an installed package. Anything you set below still wins. See docs/PROFILES.md.",
   "port": 4600,
   "google": {
     "auth": "service-account-key",

package/ops/doctor.py

@@ -55,6 +55,30 @@ def check_engine():
         report("OK", "update check has not run yet", "it runs with the daily run")
 
 
+def check_profile(cfg):
+    """A profile that cannot be resolved must be loud.
+
+    Someone running a client's portfolio on their agency's method should never
+    discover it quietly stopped applying and the engine defaults took over.
+    """
+    spec = cfg.get("profile")
+    if not spec:
+        return
+    print("profile")
+    d = seo_config.profile_dir(spec)
+    if not d:
+        report("FAIL", f"profile {spec!r} not found",
+               "install it, fix the path, or remove \"profile\" from the config")
+        return
+    try:
+        meta = json.loads((d / "n-seo.profile.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        report("FAIL", f"profile {spec!r} is unreadable", str(exc)[:120])
+        return
+    report("OK", f"{meta.get('name', spec)}" + (f" {meta['version']}" if meta.get("version") else ""))
+    report("OK", f"from {d}")
+
+
 def check_config():
     print("config")
     if seo_config.using_example():
@@ -309,6 +333,8 @@ def check_modules(cfg):
 def main():
     check_engine()
     cfg = check_config()
+    if cfg is not None:
+        check_profile(cfg)
     check_tools()
     if cfg is None:
         return 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n-seo",
-  "version": "0.4.1",
+  "version": "0.5.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,20 @@
+{
+  "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.",
+  "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 }
+  }
+}

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,13 @@ 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"], .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 } 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];

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,86 @@ 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 };
+}
+
+/** 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;
+}
+
+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 },
+};
+
+export const DEFAULT_OPERATING_RULES: OperatingRules = {
+  titleFreezeDays: 28,
+  metadataChangesPerWeek: 8,
+  decisionWindowDays: 90,
+  historyMonths: 16,
+};
+
 export interface Config {
   name: string;
   port: number;
@@ -102,6 +183,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 +218,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 +317,12 @@ 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.
+    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.`);
+}

package/src/profile-report.ts

@@ -0,0 +1,106 @@
+/** What profile is active, and exactly where this instance departs from it.
+ *
+ *  The second half is the point. Someone running a client's portfolio on an
+ *  agency's method needs to see, at a glance, which numbers came from the
+ *  agency and which they changed themselves — otherwise "we follow your
+ *  model" is an unverifiable claim. */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  CONFIG_PATH, EXAMPLE_CONFIG_PATH, PROFILE_FILE, DEFAULT_RULES, DEFAULT_OPERATING_RULES,
+  ROOT, config, loadProfile, type Profile,
+} from "./config.js";
+
+export interface Departure {
+  /** Dotted path, e.g. "rules.strikingDistance.maxRows". */
+  key: string;
+  /** What the layer beneath says: the profile, or the engine defaults. */
+  inherited: unknown;
+  /** What this instance sets instead. */
+  instance: unknown;
+}
+
+export interface ProfileReport {
+  /** The `profile` value from the config, if any. */
+  spec?: string;
+  name: string;
+  description?: string;
+  version?: string;
+  dir?: string;
+  departures: Departure[];
+}
+
+/** Flatten a nested tree to dotted leaves, so two layers can be diffed. */
+function flatten(v: unknown, prefix = "", out: Record<string, unknown> = {}) {
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    for (const [k, val] of Object.entries(v)) flatten(val, prefix ? `${prefix}.${k}` : k, out);
+  } else if (prefix) {
+    out[prefix] = v;
+  }
+  return out;
+}
+
+function mergeDeep<T>(base: T, over: unknown): T {
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  if (over && typeof over === "object") {
+    for (const [k, v] of Object.entries(over as Record<string, unknown>)) {
+      if (v === undefined) continue;
+      const cur = out[k];
+      out[k] = cur && typeof cur === "object" && v && typeof v === "object" && !Array.isArray(v)
+        ? mergeDeep(cur, v)
+        : v;
+    }
+  }
+  return out as T;
+}
+
+/** The config as written, not the normalized one. Normalization has already
+ *  merged the layers, so it can no longer say who set what. */
+function rawConfig(): Record<string, unknown> {
+  const p = fs.existsSync(CONFIG_PATH) ? CONFIG_PATH : EXAMPLE_CONFIG_PATH;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function profileReport(): ProfileReport {
+  const cfg = config();
+  const raw = rawConfig();
+  const loaded = cfg.profile ? loadProfile(cfg.profile) : null;
+  const profile = loaded?.profile ?? null;
+
+  const inherited = flatten({
+    rules: mergeDeep(DEFAULT_RULES, profile?.rules),
+    operatingRules: mergeDeep(DEFAULT_OPERATING_RULES, profile?.operatingRules),
+  });
+  const instanceSet = flatten({ rules: raw.rules, operatingRules: raw.operatingRules });
+
+  const departures = Object.entries(instanceSet)
+    .filter(([key, value]) => inherited[key] !== value)
+    .map(([key, value]) => ({ key, inherited: inherited[key], instance: value }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+
+  return {
+    spec: cfg.profile,
+    name: profile?.name ?? "engine defaults",
+    description: profile?.description,
+    version: profile?.version,
+    dir: loaded?.dir,
+    departures,
+  };
+}
+
+/** Profiles shipped with the engine. */
+export function builtinProfiles(): { spec: string; name: string; description?: string }[] {
+  const dir = path.join(ROOT, "profiles");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, PROFILE_FILE)))
+    .map((e) => {
+      const p = JSON.parse(fs.readFileSync(path.join(dir, e.name, PROFILE_FILE), "utf8")) as Profile;
+      return { spec: e.name, name: p.name || e.name, description: p.description };
+    })
+    .sort((a, b) => a.spec.localeCompare(b.spec));
+}

package/src/settings.tsx

@@ -7,6 +7,7 @@ import path from "node:path";
 import type { FC } from "hono/jsx";
 import { CONFIG_PATH, MODULE_INFO, config, saveConfig, USING_EXAMPLE_CONFIG, loadConfig, engineInfo } from "./config.js";
 import * as data from "./data.js";
+import { profileReport, builtinProfiles } from "./profile-report.js";
 
 const expand = (p: string) => (p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p);
 
@@ -32,6 +33,8 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
   const lr = data.lastRun();
   const eng = engineInfo();
   const upd = data.updateCheck();
+  const prof = profileReport();
+  const builtins = builtinProfiles();
   const hookCount = cfg.hooks.beforeRun.length + cfg.hooks.afterRun.length + Object.values(cfg.hooks.afterStep).reduce((n, l) => n + l.length, 0);
   const str = (v: unknown) => (v == null ? "" : String(v));
   return (
@@ -75,6 +78,34 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
             </p>
           )}
         </div>
+        <div class="s-card">
+          <div class="s-title">
+            Profile: {prof.name}{prof.version ? ` ${prof.version}` : ""}
+            {prof.departures.length > 0 && <span class="chip"> {prof.departures.length} override{prof.departures.length === 1 ? "" : "s"}</span>}
+          </div>
+          {prof.description && <p class="sub">{prof.description}</p>}
+          {!prof.spec && (
+            <p class="sub">
+              No profile set, so the engine defaults apply. Shipped with this engine:{" "}
+              {builtins.map((b, i) => <>{i > 0 ? ", " : ""}<code>{b.spec}</code></>)}. Set one with{" "}
+              <code>"profile"</code> in the config, or point it at a directory or an installed package.
+            </p>
+          )}
+          {prof.departures.length > 0 && (
+            <>
+              <p class="sub">Changed here, against the {prof.spec ? "profile" : "engine defaults"}:</p>
+              <ul class="prof-diff">
+                {prof.departures.map((d) => (
+                  <li>
+                    <span class="mono">{d.key}</span>
+                    <span class="prof-was">{JSON.stringify(d.inherited)}</span>
+                    <span class="prof-now">{JSON.stringify(d.instance)}</span>
+                  </li>
+                ))}
+              </ul>
+            </>
+          )}
+        </div>
         <div class="s-card">
           <div class="s-title">Instance path</div>
           <div class="mono">{eng.instance}</div>