n-seo 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -8,6 +8,48 @@ uses [Semantic Versioning](https://semver.org/).
 
 Nothing yet.
 
+## [0.6.0] - 2026-09-15
+
+### Added
+- **Profiles carry principles.** Building the first real profile showed the
+  format was too thin. Measured against ten sites, one practitioner's method
+  was barely distinguishable from the engine's in *thresholds* — rows sort by
+  impressions before the cap, so the striking-distance floor never binds where
+  there is data, and lowering it would only have deleted the one marginal
+  site's two cards — and almost entirely distinguishable in *judgement*.
+  `principles` carries that: a title, a body, and a kind. `hard` is a
+  constraint an agent must not cross; `guide` is judgement it should apply.
+  They render at the top of the action queue and on Settings, and `n-seo init`
+  writes them into the instance's `CLAUDE.md`. A principle the agent never
+  reads is a note to yourself, not an operating rule.
+- **`rules.priorities` — custom rules, declaratively.** A threshold says what
+  counts as a finding; a priority says what you care about. Match on `host`,
+  `pathMatches`, `tag` or `kind`, then `multiply` the impact that orders the
+  queue, or `drop` the card. Several compound in the order written.
+- Two constraints the design will not bend on. **A priority may reorder or
+  hide, never invent** — it cannot create a card, so it cannot manufacture
+  evidence. And **every card it touches says so**, carrying the reason in its
+  spec and a *reweighted* chip; `why` is required and a priority without one
+  is ignored. Ordering you cannot see the reason for is ordering you cannot
+  argue with.
+- A priority with no conditions matches nothing, a bad regular expression
+  matches nothing rather than throwing, and a nonsense multiplier is ignored
+  rather than corrupting the sort.
+
+### Decided
+- **Profiles still may not ship executable code.** The obvious version of
+  custom rules is letting a profile carry a function. Installing someone's
+  method would then mean running their program on the machine holding your
+  Search Console credentials and your service-account key — a large amount of
+  trust for a list of thresholds. Matching and weighting turned out to cover
+  what people actually wanted to express. A genuinely new *kind* of card, one
+  reading data no existing rule reads, remains a fork and remains the open
+  question.
+
+### Fixed
+- `.chip` ellipsizes at 34ch and shrinks as a flex item, which rendered the
+  word "hard" as "h…" on every principle.
+
 ## [0.5.0] - 2026-09-14
 
 The operating model was ours, hardcoded. Now it is a file you can install.
@@ -444,7 +486,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.5.0...HEAD
+[Unreleased]: https://github.com/en-dash-consulting/n-seo/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/en-dash-consulting/n-seo/compare/v0.5.0...v0.6.0
 [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

package/bin/n-seo.mjs

@@ -144,6 +144,41 @@ function missingDeps(cmd, what) {
   return 1;
 }
 
+/** A profile's principles, as markdown for the instance CLAUDE.md.
+ *
+ *  The whole point of writing a method down is that the agent follows it too.
+ *  A principle that lives only in the dashboard is a principle the thing
+ *  doing the work never reads. */
+function profilePrinciples(dir) {
+  const cfgPath = path.join(dir, "n-seo.config.json");
+  let spec;
+  try {
+    spec = JSON.parse(fs.readFileSync(cfgPath, "utf8")).profile;
+  } catch { return ""; }
+  if (!spec) return "";
+
+  const candidates = [
+    path.join(ROOT, "profiles", spec),
+    path.isAbsolute(spec) ? spec : path.resolve(dir, spec),
+    path.join(dir, "node_modules", spec),
+    path.join(ROOT, "node_modules", spec),
+  ];
+  const found = candidates.find((c) => fs.existsSync(path.join(c, "n-seo.profile.json")));
+  if (!found) return "";
+
+  let profile;
+  try {
+    profile = JSON.parse(fs.readFileSync(path.join(found, "n-seo.profile.json"), "utf8"));
+  } catch { return ""; }
+  const list = (profile.principles ?? []).filter((p) => p?.title && p?.body);
+  if (!list.length) return "";
+
+  const lines = list.map((p) => `- **${p.title}**${p.kind === "hard" ? " (hard rule)" : ""}\n  ${p.body}`);
+  return `\n## From the ${profile.name} profile\n\n` +
+    `These came with the profile this instance runs. Hard rules are constraints, not advice.\n\n` +
+    lines.join("\n") + "\n";
+}
+
 /* ---------- init ---------- */
 
 /** Files that mean "this directory is an application", not a place to keep
@@ -304,7 +339,7 @@ Skills in \`.claude/skills/\` cover the routine work — start with
   /actions until a human accepts them.
 - **Site changes ship as branches and pull requests** in the site's own repo,
   never committed straight to its main branch.
-`);
+${profilePrinciples(dir)}`);
 
   const envExample = path.join(ROOT, ".env.example");
   put(".env", fs.existsSync(envExample) ? fs.readFileSync(envExample, "utf8") : "");

package/docs/PRD.md

@@ -157,10 +157,19 @@ published once and installed many times. Full reference: `docs/PROFILES.md`.
 - Acceptance: `default`, `patient` and `aggressive` ship with the engine, and
   `default` restates the engine defaults exactly — asserted, so the two cannot
   drift.
+- Acceptance: `rules.priorities` reweights or drops queue cards by host,
+  path, tag or kind; a matched card carries the reason in its spec and a
+  *reweighted* chip; a priority with no `why` or no conditions is ignored; a
+  bad regex or a nonsense multiplier is ignored rather than throwing or
+  corrupting the sort.
+- Acceptance: a priority can never create a card. Everything in the queue
+  still came from data.
 - 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.
+  your Search Console credentials. `priorities` covers reordering and hiding
+  declaratively, which is what practitioners actually asked to express. A
+  genuinely new *kind* of card — one reading data no existing rule reads —
+  remains a fork, and is the open question.
 
 ## Feature: Rule thresholds in config [shipped]
 

package/docs/PROFILES.md

@@ -75,10 +75,40 @@ this instance overrides 2 value(s):
   // Module defaults. The instance can still switch any of them.
   "modules": {
     "indexNow": { "enabled": true }
-  }
+  },
+
+  // The parts of a method that are not a number.
+  "principles": [
+    {
+      "kind": "hard",
+      "title": "Never write to a CMS without per-item approval",
+      "body": "Show the exact before and after, get a yes on each one, then write."
+    },
+    { "title": "Judge by the path to a signup, not by clicks", "body": "..." }
+  ]
 }
 ```
 
+### Principles
+
+The most useful thing we learned building the first real profile: a
+practitioner's method is barely distinguishable from ours in *thresholds* and
+almost entirely distinguishable in *judgement*. The striking-distance floor
+turned out never to bind once rows are sorted by impressions. What actually
+differed was what to optimise for, what needs a human's approval, and what to
+never automate.
+
+None of that is a number, so `principles` carries it. Each has a `title`, a
+`body`, and a `kind`:
+
+- **`hard`** — a constraint. An agent must not cross it.
+- **`guide`** — judgement it should apply.
+
+They appear at the top of the action queue, on the Settings page, and — this
+is the part that matters — `n-seo init` writes them into the instance's
+`CLAUDE.md`. A principle the agent never reads is not an operating rule, it is
+a note to yourself.
+
 Set only what you disagree with. Anything absent is inherited, so a profile
 that changes one threshold is three lines long.
 
@@ -115,6 +145,61 @@ 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.
 
+## Priorities — the declarative half of custom rules
+
+A threshold says *what counts as a finding*. A priority says *what you care
+about*. They are different questions, and the second one is where a method
+usually lives.
+
+```jsonc
+"rules": {
+  "priorities": [
+    {
+      "why": "leads somewhere: a signup, a tool, an account",
+      "when": { "pathMatches": "^/(tools|pricing|signup)" },
+      "multiply": 1.5
+    },
+    {
+      "why": "we have decided not to work on these",
+      "when": { "pathMatches": "^/legal/" },
+      "drop": true
+    }
+  ]
+}
+```
+
+`when` matches on `host`, `pathMatches` (a regular expression against the
+page's path), `tag`, and `kind`. A priority with no conditions matches
+nothing — applying to the whole queue is never what anyone means, and is a
+miserable way to learn the shape of the config.
+
+`multiply` scales the impact that orders the queue. `drop` removes the card.
+Several priorities compound, in the order they are written.
+
+### Two rules the design will not bend on
+
+**A priority may reorder or hide, never invent.** It cannot create a card, so
+it cannot manufacture evidence. Everything in the queue still came from data.
+
+**Every card it touches says so.** The impact number decides the order, so a
+card whose number was adjusted carries the reason on its face and a
+*reweighted* chip. `why` is required; a priority without one is ignored.
+Ordering you cannot see the reason for is ordering you cannot argue with, and
+the whole product rests on showing its working.
+
+### Why this is not a plugin API
+
+The obvious version of "custom rules" is letting a profile ship code. We are
+not doing that, and the reason is not squeamishness about JavaScript:
+installing someone's method would mean running their program on the machine
+that holds your Search Console credentials and your service-account key. That
+is a large amount of trust to ask for a list of thresholds.
+
+Matching and weighting turned out to cover what people actually want to
+express. A genuinely new *kind* of card — one that reads data no existing rule
+reads — is still a fork, and `docs/PRD.md` carries that as an open question
+rather than a decided one.
+
 ## When a profile cannot be found
 
 The run fails, loudly, naming every location that was tried. It does **not**

package/ingest/seo_config.py

@@ -72,6 +72,9 @@ DEFAULT_RULES = {
     "trafficDrop": {"minPriorSessions": 50, "dropRatio": 0.75},
     "probe": {"minVisibleTextBytes": 500},
     "metadata": {"maxFindings": 5},
+    # Ordering adjustments. Applied by the TypeScript action engine; mirrored
+    # here so the two loaders resolve identical config, which a test asserts.
+    "priorities": [],
 }
 
 DEFAULT_OPERATING_RULES = {
@@ -103,7 +106,12 @@ def profile_dir(spec):
 
 
 def _merge(base, over):
-    """Deep merge; `over` wins, and None never overwrites."""
+    """Deep merge; `over` wins, None never overwrites, and lists replace.
+
+    Lists replace rather than concatenate so an instance that sets
+    `priorities` replaces the profile's outright. Appending would make a
+    profile's priority impossible to remove without forking the profile.
+    """
     out = dict(base)
     for k, v in (over or {}).items():
         if v is None:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n-seo",
-  "version": "0.5.0",
+  "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)",

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

@@ -1,6 +1,6 @@
 {
   "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.",
+  "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,
@@ -9,12 +9,37 @@
     "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 }
+    "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/public/styles.css

@@ -582,7 +582,22 @@ 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"], .prof-diff { list-style: none; margin: 6px 0 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
+.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; }

package/src/actions.ts

@@ -4,7 +4,7 @@
  *  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, config, 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";
 
@@ -250,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

@@ -118,6 +118,8 @@ export interface Rules {
   };
   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.
@@ -144,6 +146,28 @@ export interface Profile {
   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] };
@@ -156,6 +180,7 @@ export const DEFAULT_RULES: Rules = {
   trafficDrop: { minPriorSessions: 50, dropRatio: 0.75 },
   probe: { minVisibleTextBytes: 500 },
   metadata: { maxFindings: 5 },
+  priorities: [],
 };
 
 export const DEFAULT_OPERATING_RULES: OperatingRules = {
@@ -165,6 +190,42 @@ export const DEFAULT_OPERATING_RULES: OperatingRules = {
   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;
@@ -321,6 +382,9 @@ function normalize(raw: Partial<Config>): Config {
     // 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/profile-report.ts

@@ -8,7 +8,7 @@ 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,
+  ROOT, config, loadProfile, type Profile, type ProfilePrinciple,
 } from "./config.js";
 
 export interface Departure {
@@ -28,6 +28,7 @@ export interface ProfileReport {
   version?: string;
   dir?: string;
   departures: Departure[];
+  principles: ProfilePrinciple[];
 }
 
 /** Flatten a nested tree to dotted leaves, so two layers can be diffed. */
@@ -89,6 +90,7 @@ export function profileReport(): ProfileReport {
     version: profile?.version,
     dir: loaded?.dir,
     departures,
+    principles: (profile?.principles ?? []).filter((p) => p?.title && p?.body),
   };
 }
 

package/src/settings.tsx

@@ -91,6 +91,16 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
               <code>"profile"</code> in the config, or point it at a directory or an installed package.
             </p>
           )}
+          {prof.principles.length > 0 && (
+            <>
+              <p class="sub">{prof.principles.length} principle{prof.principles.length === 1 ? "" : "s"}, shown in full on <a href="/actions">Actions</a>.</p>
+              <ul class="prof-princ">
+                {prof.principles.map((pr) => (
+                  <li><span class={`chip ${pr.kind === "hard" ? "bad" : ""}`}>{pr.kind === "hard" ? "hard" : "guide"}</span> {pr.title}</li>
+                ))}
+              </ul>
+            </>
+          )}
           {prof.departures.length > 0 && (
             <>
               <p class="sub">Changed here, against the {prof.spec ? "profile" : "engine defaults"}:</p>

package/src/views.tsx

@@ -2,6 +2,7 @@
 import type { FC, PropsWithChildren } from "hono/jsx";
 import { SITES, ENGINE_VERSION, config, loadConfig, USING_EXAMPLE_CONFIG, type SiteCfg } from "./config.js";
 import * as data from "./data.js";
+import { profileReport } from "./profile-report.js";
 import { actionsFor, allActions, type Action } from "./actions.js";
 import { insights as loadInsights } from "./insights.js";
 
@@ -140,7 +141,18 @@ export const ActionModal: FC<{ a: Action; id: string }> = ({ a, id }) => (
       <span class={`chip effort e-${a.effort}`}>{effortLabel(a.effort, true)}</span>
       <span class="chip tag">{a.tag}</span>
       <span class="chip">{a.source === "backlog" ? "curated" : a.source === "proposal" ? "proposed" : "data-derived"}</span>
+      {a.priorityNotes?.length ? (
+        <span class="chip warn" title="a configured priority changed where this sits in the queue">reweighted</span>
+      ) : null}
     </div>
+    {a.priorityNotes?.length ? (
+      // The impact number decides the order, so a card whose number was
+      // adjusted has to say so on its face. Ordering you cannot see the
+      // reason for is ordering you cannot argue with.
+      <ul class="prio-notes">
+        {a.priorityNotes.map((n) => <li>{n}</li>)}
+      </ul>
+    ) : null}
     {a.watching && <p class="action-watching">⏳ {a.watching}</p>}
     <h4>Why (the data)</h4>
     <p>{a.why}</p>
@@ -265,6 +277,9 @@ const ProposalCard: FC<{ p: data.ScanOutput["proposals"][number]; index: number
 
 export const ActionsPage: FC<{ flash?: string }> = ({ flash }) => {
   const scan = data.opportunityScan();
+  const prof = profileReport();
+  const principles = prof.principles;
+  const profileName = prof.name;
   return (
     <>
       <div class="strip-head">
@@ -274,6 +289,21 @@ export const ActionsPage: FC<{ flash?: string }> = ({ flash }) => {
       <p class="sub">Data-derived rules (90-day window) + your curated queue (<code>config/backlog.json</code>). Click any item for the full spec. Impact numbers rank the queue — they are estimates for ordering, not forecasts.</p>
       {flash && <p class="flash">{flash}</p>}
 
+      {principles.length > 0 && (
+        <details class="wb-fold princ">
+          <summary>
+            Operating principles <small>— from the {profileName} profile; {principles.filter((p) => p.kind === "hard").length} are constraints, not advice</small>
+          </summary>
+          <div class="princ-list">
+            {principles.map((p) => (
+              <div class={`princ-item ${p.kind === "hard" ? "hard" : ""}`}>
+                <div class="princ-h"><span class={`chip ${p.kind === "hard" ? "bad" : ""}`}>{p.kind === "hard" ? "hard" : "guide"}</span> <b>{p.title}</b></div>
+                <p>{p.body}</p>
+              </div>
+            ))}
+          </div>
+        </details>
+      )}
       {scan && (scan.proposals.length > 0 || scan.verdicts.length > 0) && (
         <div class="scan-panel" id="proposed">
           <h2>Proposed by the opportunity scan <small>· {scan.generated} — rising queries no queue item covers, turned into candidate moves. Accepting copies a proposal into your queue; nothing self-modifies it.</small></h2>