clearotron 0.2.2 → 0.2.4

package/bin/start.mjs

@@ -116,7 +116,7 @@ import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "
 // tolerate and never manage"; settled point 2 superseded that.)
 import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
 import { createServer } from "node:net";
-import { listenErrorMessage } from "../shared/listen.mjs";
+import { listenErrorMessage, nextFreePort } from "../shared/listen.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { invocationPrefix, invoke } from "../shared/invocation.mjs";   // — the banner names the verb
@@ -130,6 +130,11 @@ import { productIdentity } from "../shared/product-identity.mjs";   // AGPL §13
 import { pinEnvAll } from "../shared/env-aliases.mjs";   // — a pin that names one spelling has set nothing that wins
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
 import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // never serve a bundle older than its sources
+// ONE CLASSIFIER FOR WHAT A STAFF RULE ADMITS, shared with the setup wizard. Two copies of this
+// judgement would be a wizard that asks about one rule and a launcher that writes another.
+import { classifyStaffDomain, staffDomainRefusal, staffGrantSentence } from "../shared/staff-domain.mjs";
+import { backgroundManager } from "../shared/os-advice.mjs";
+import { frontingVariablesSet } from "../shared/install-auth.mjs";   // — one owner for what counts as a proxy in front of a door
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed: one resolver, so moving this file later is one line
@@ -366,6 +371,11 @@ export function installPaths(base) {
   };
 }
 
+/** A staff rule this command will not build. Carries the sentence the operator reads, and why. */
+export class StaffDomainRefused extends Error {
+  constructor(domain, message) { super(message); this.name = "StaffDomainRefused"; this.domain = domain; }
+}
+
 /**
  * The one address that signs in, and the staff domain derived from it.
  *
@@ -374,10 +384,61 @@ export function installPaths(base) {
  * it safe here and would not be safe on a hosted instance. Without it the sign-in succeeds and every
  * page 403s, because signing in is not being enrolled (portal-access.mjs decides that, and it is
  * deliberately blind to which door you came through).
+ *
+ * ── AND THAT PARAGRAPH IS ONLY TRUE OF `<account>@localhost` ─────────────────────────────────────────
+ *
+ * "admits exactly that address and nobody else" is a property of the DOMAIN, not of the mode. It holds
+ * for `localhost`. It does not hold for a domain other people have addresses at: the rule this line
+ * produces from `alex@a-firm.example-tld` says *anyone at that domain*, the settings page then reports
+ * it back in those words, and on a deployment where identity arrives from an external login system the
+ * domain is the whole of the check. Nobody was asked, and there is nothing on the box recording that a
+ * grant was made.
+ *
+ * So the derivation now refuses the domains that can never be a staff rule — a webmail provider, a
+ * documentation domain — and hands anything wider than one machine back to the caller to state and
+ * confirm. `shared/staff-domain.mjs` is the one classifier, shared with the setup wizard, so the
+ * question the wizard asks and the rule this command builds cannot drift apart.
+ *
+ * An UNPARSEABLE address still returns `""`, and that is not the same answer as a refusal: nothing was
+ * classified, so nothing was decided. The caller already refuses a non-address one line earlier.
  */
 export function staffDomainFor(email) {
   const at = String(email ?? "").lastIndexOf("@");
-  return at > 0 ? String(email).slice(at + 1).toLowerCase() : "";
+  const domain = at > 0 ? String(email).slice(at + 1).toLowerCase() : "";
+  if (!domain) return "";
+  const refusal = staffDomainRefusal(domain);
+  if (refusal) throw new StaffDomainRefused(domain, refusal);
+  return domain;
+}
+
+/**
+ * What to say when the derived domain is a real one — wider than this machine, and never assumed.
+ *
+ * A REFUSAL RATHER THAN A PROMPT, and the reason is that this command has no reader. `start` runs from
+ * a script, from `--background`, and from a service manager as often as from a terminal; a question
+ * asked there either hangs or is answered by whatever happens to be on stdin. Every other decision on
+ * this boundary already refuses instead — an unset access file, a multi-`@` identity, local mode off
+ * loopback — so this is the idiom the rest of the door speaks.
+ *
+ * The consent itself lives where a person is definitionally present: `clearotron install` asks for the
+ * address, shows this same sentence, and writes the answer down as an explicit `PORTAL_STAFF_DOMAINS`.
+ * After that the `||` above this call short-circuits and the derivation is never reached again.
+ */
+export function wideStaffDomainRefusal({ user, domain, envPath }) {
+  return `${user} would make every address at ${domain} an administrator of this install.\n`
+    + "\n"
+    + `  The rule that would be written is:  ${staffGrantSentence(domain, { staffLabel: `${BRAND.name} staff` })}\n`
+    + "\n"
+    + "  That is a grant to a group, and this command will not make one on your behalf. Pick the one\n"
+    + "  that is true here:\n"
+    + "\n"
+    + `    · only you use this machine — start without --user, or use ${String(user).slice(0, String(user).lastIndexOf("@"))}@localhost.\n`
+    + `      The rule is then this machine and nobody else, and nothing is granted to anyone.\n`
+    + `    · your colleagues at ${domain} should all be administrators — say so once, in writing:\n`
+    + `        PORTAL_STAFF_DOMAINS=${domain}\n`
+    + `      in ${envPath}, or in the environment. The settings page then names that file as where the\n`
+    + "      rule came from, so whoever reads it later can undo it.\n"
+    + `    · run \`${invocationPrefix()}clearotron install\`, which asks for the address and this question with it.`;
 }
 
 /**
@@ -777,6 +838,10 @@ if (isMain) {
   // bound anywhere else in any mode. Sign-in is untouched — the demo signs in like any first start, and
   // the portal mints and prints its passphrase exactly as it does for a real one.
   const DEMO = argv.includes("--demo");
+  // THE DEMO BRINGS ITS OWN ACCOUNT. A fresh install resolves `generic` and nothing else (owner
+  // ruling, 2026-09-08), so the demo account is refused from the roster unless somebody asked for it.
+  // Asked here, once and visibly, rather than at each site that happens to read a roster.
+  if (DEMO) process.env.CLEAROTRON_DEMO_PROFILES ??= "1";
   // ── `--port` MOVES EVERY DOOR IT OPENS (tracker issue 166) ───────────────────────────────────────
   //
   // It used to move ONE of the three. `resolvePorts` reads three independent variables with three
@@ -812,16 +877,47 @@ if (isMain) {
     run: (cmd, args) => spawnSync(cmd, args, { cwd: REPO, stdio: "inherit", shell: process.platform === "win32" }).status ?? 1,
   });
 
-  // Nobody is asked for this. A local install has one user, this machine already knows their name, and
-  // the address never leaves the machine — `--user` is there for a reader who wants their real one, and
-  // whatever is resolved here is written to `.env` so the question is never put twice.
+  // The ADDRESS is not asked for here: a local install has one user, this machine already knows their
+  // name, and the address never leaves the machine — `--user` is there for a reader who wants their real
+  // one, and whatever is resolved here is written to `.env` so the question is never put twice. What IS
+  // asked for, and used not to be, is the staff rule the address implies once it is a real one; that is
+  // the block below the address, and `clearotron install` is where the question is actually put.
   let whoami = "user";
   try { whoami = userInfo().username || "user"; } catch { /* a container with no passwd entry */ }
   // In a demo the address is the demo's own and is never written anywhere: see the DEMO block above.
   const user = String(flag("--user", DEMO ? "demo@localhost" : (process.env.PORTAL_LOCAL_USER || `${whoami}@localhost`))).trim().toLowerCase();
   if (!user.includes("@") || user.indexOf("@") !== user.lastIndexOf("@"))
     fatal(`--user "${user}" is not a single email address. It is the one identity that signs in here, and the portal refuses a multi-@ identity outright.`);
-  const staffDomains = process.env.PORTAL_STAFF_DOMAINS || staffDomainFor(user);
+  // ── THE STAFF RULE THIS ADDRESS IMPLIES, STATED BEFORE IT IS WRITTEN ──────────────────────────────
+  //
+  // An explicit `PORTAL_STAFF_DOMAINS` is a decision somebody already made in writing, and it wins
+  // untouched — including a domain the classifier would otherwise refuse, because an operator who
+  // typed it has said what they mean and this command does not overrule that.
+  //
+  // Absent one, the rule is DERIVED from the single address, and that derivation is the defect this
+  // block exists to close. Three outcomes:
+  //
+  //   `localhost` (or any bare hostname)  — one machine, no second person, nothing to ask. Silent, as
+  //                                         it has always been. This is the default path and the only
+  //                                         one a laptop ever reaches.
+  //   a webmail or documentation domain   — refused by `staffDomainFor` itself; there is no yes that
+  //                                         makes it right.
+  //   any other real domain               — refused HERE, with the rule quoted in the words the
+  //                                         settings page uses and the three ways out named.
+  //
+  // BEFORE THIS RUN CHANGES THE BOX, deliberately — it sits above the state-written divide further
+  // down, with the units gate, the auth-mode gate and the port probe. A refused start has written no
+  // `.env`, minted no secret and placed no unit, so the reader's only question — is my install
+  // half-made — has one answer.
+  let staffDomains = process.env.PORTAL_STAFF_DOMAINS;
+  if (!staffDomains) {
+    let derived = "";
+    try { derived = staffDomainFor(user); }
+    catch (e) { fatal(e.message); }
+    if (derived && classifyStaffDomain(derived) === "wide")
+      fatal(wideStaffDomainRefusal({ user, domain: derived, envPath: ENV_PATH }));
+    staffDomains = derived;
+  }
 
   say("");
   say(`  ${BRAND.name} ${BRAND.product.toLowerCase()} — local install`);
@@ -868,7 +964,24 @@ if (isMain) {
   // loop because both paths below have to act on it: the background path must RESTART the door it
   // adopted, and the foreground path must not spawn a second one beside it.
   let adoptedClientDoor = false;
-  for (const [what, port, portVar, doorUnit = null] of [["portal", ports.portal, "PORTAL_SERVICE_PORT"], ["engine door", ports.mcp, "TRADEMARK_MCP_HTTP_PORT"], ["client door", ports.client, "CLIENT_MCP_HTTP_PORT", CLIENT_DOOR_UNIT]]) {
+  // ── WHETHER ANYTHING OUTSIDE THIS PROCESS IS ADDRESSED TO THESE NUMBERS ────────────────────────
+  //
+  // A door may only be moved off a port nobody chose when nothing fronts it. A proxy, an Access team
+  // or an OIDC issuer means something external resolves to these numbers, and a door that quietly
+  // moved would be up and unreachable — which looks like success and is the worst of the three
+  // outcomes. The auth-mode half of this is already closed further up: a foreground start refuses
+  // outright when PORTAL_AUTH_MODE names a hosted door, and again when the units are installed and
+  // serving. What is left to check is the settings that can be present with the mode unset.
+  //
+  // PORTAL_AUTH_MODE IS ABSENT FROM THAT LIST ON PURPOSE, and only a rule in another file makes that
+  // safe: `driver/portal-service.mjs` refuses to start in auth-proxy without CF_ACCESS_TEAM or
+  // PORTAL_OIDC_ISSUER, so a portal fronted by the mode alone cannot come up at all. Relaxing that
+  // refusal without adding the mode here would let this under-report — which is why the list has one
+  // owner in `shared/install-auth.mjs` with an arm holding it to the doors themselves.
+  const fronted = frontingVariablesSet(process.env);
+  const claimedPorts = new Set([ports.portal, ports.mcp, ports.client]);
+  const movedDoors = [];
+  for (const [what, port, portVar, doorUnit = null, key = null] of [["portal", ports.portal, "PORTAL_SERVICE_PORT", null, "portal"], ["engine door", ports.mcp, "TRADEMARK_MCP_HTTP_PORT", null, "mcp"], ["client door", ports.client, "CLIENT_MCP_HTTP_PORT", CLIENT_DOOR_UNIT, "client"]]) {
     // A --background REFRESH runs over its own healthy units, which hold these ports on purpose;
     // systemd's restart is the handover. Probing would refuse the flag exactly once it has worked.
     // The narrow carve above already proved every installed unit is ours.
@@ -893,8 +1006,38 @@ if (isMain) {
     // on a privileged port and from an address this host does not have, and names the way out of each;
     // the launcher having its own shorter sentence for one of the three would mean a user meets two
     // different answers to the same question depending on which door refused first.
+    // ── A PORT NOBODY CHOSE IS MOVED RATHER THAN REFUSED (owner ruling, 2026-09-09) ─────────────
+    //
+    // Three conditions, and each is a different reason:
+    //   · the address is genuinely taken — anything else is not this case;
+    //   · the reader did not state this port, so no one is addressed to it. An explicitly set port is
+    //     a stated address and is refused exactly as before;
+    //   · nothing fronts these doors, so nothing outside resolves to the old number.
+    // With any of those false the refusal below fires unchanged, which is the whole of the previous
+    // behaviour kept intact underneath this.
+    if (code === "EADDRINUSE" && key && !fronted.length && !String(process.env[portVar] ?? "").trim()) {
+      const next = await nextFreePort(port, async (p) => (await probe(p)) === null, { claimed: claimedPorts });
+      // NULL IS NOT A FALLBACK. Nothing free in range means the reader is told the truth about the
+      // port they asked for, rather than sent to one this could not prove was free either.
+      if (next) {
+        claimedPorts.delete(port);
+        claimedPorts.add(next);
+        ports[key] = next;
+        movedDoors.push({ what, portVar, from: port, to: next });
+        continue;
+      }
+    }
     if (code) fatal(listenErrorMessage({ code }, { what, host: HOST, port, portVar, portFile }));
   }
+  // SAID OUT LOUD, EVERY TIME. A door that moved is at an address the reader did not ask for and will
+  // not find by memory — and the portal's own URL is printed from `ports.portal` further down, so a
+  // silent move would leave the two disagreeing with nothing explaining it.
+  if (movedDoors.length) {
+    say("");
+    say(`  ${movedDoors.length === 1 ? "One door was" : `${movedDoors.length} doors were`} already in use, so ${movedDoors.length === 1 ? "it" : "they"} moved:`);
+    for (const d of movedDoors) say(`    the ${d.what}: ${d.from} → ${d.to}   (set ${d.portVar} to pin it)`);
+    say("  Nothing outside this machine is addressed to these, so nothing else needed changing.");
+  }
 
   // ── 2. the two secrets, generated once and kept ────────────────────────────────────────────────────
 
@@ -1574,10 +1717,40 @@ if (isMain) {
       // sequence rather than a race between the terminal's signal and ours. It also means the group
       // kill below reaches anything a child spawns, not just the child.
       detached: true,
-      stdio: ["ignore", "inherit", "inherit"],
+      // — STDERR IS TEED RATHER THAN INHERITED, AND ONLY STDERR.
+      //
+      // These children announce a refusal as one FATAL line on stderr and exit 1. With `inherit` the
+      // parent holds no copy, so the failure message below could only point at output it had never seen —
+      // and on one report that output never reached the reader's terminal at all. It said "its own output
+      // above says why" about a line that was not above, which is worse than saying nothing: it sends
+      // somebody scrolling for a sentence they will not find.
+      //
+      // stdout stays inherited. It carries no refusal — measured: on a refusing door stdout is empty and
+      // stderr holds the whole of it — and leaving it alone keeps the child's terminal detection and any
+      // progress rendering intact. Piping a stream costs the child its TTY, so only the stream that has to
+      // be read is piped.
+      stdio: ["ignore", "inherit", "pipe"],
       env: { ...process.env, ...env },
     });
-    const rec = { name, script, child, alive: true };
+    // The last lines of that child's stderr, forwarded on as they arrive so nothing is delayed or
+    // swallowed, and kept so the failure can QUOTE them rather than refer to them.
+    const tail = [];
+    // A CHUNK IS NOT A LINE. `data` arrives on whatever boundary the pipe gives us, so a stream split
+    // mid-sentence would push two half-lines and the quoted last words would reach the reader cut in
+    // half — on precisely the message that exists because they could not see the original. The partial
+    // remainder is held over and completed by the next chunk; whatever is left when the stream ends is
+    // flushed, because a process that dies mid-line still said the thing it was saying.
+    let pending = "";
+    const keep = (line) => { if (line.trim()) tail.push(line); while (tail.length > 12) tail.shift(); };
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      process.stderr.write(chunk);
+      const parts = (pending + String(chunk)).split("\n");
+      pending = parts.pop() ?? "";
+      for (const line of parts) keep(line);
+    });
+    child.stderr?.on("end", () => { keep(pending); pending = ""; });
+    const rec = { name, script, child, alive: true, tail };
     children.push(rec);
     child.on("exit", (code, signal) => {
       rec.alive = false;
@@ -1590,7 +1763,7 @@ if (isMain) {
           + ` but nothing is draining the queue now. Start one with:\n    node ${script} --watch\n`);
         return;
       }
-      err(`\nstart: ${name} (${script}) exited ${signal ? `on ${signal}` : `with code ${code}`} — its own output above says why. Stopping the rest.\n`);
+      err(childExitReport({ name, script, code, signal, tail }));
       void shutdown(1);
     });
     child.on("error", (e) => {
@@ -1857,7 +2030,42 @@ if (isMain) {
   // run". Saying it here, before the commands go by, is the whole fix.
   say("  This terminal is now the product: it runs only while this command does, and Ctrl-C — or closing");
   say("  the window — stops everything it started. So the commands above need a SECOND terminal.");
-  say(`  To get your prompt back instead, stop this and run  ${invoke("start")} --background`);
-  say("  — same product, managed by systemd, and it survives logout.");
+  // ── THE BACKGROUND ROUTE IS NOT OFFERED WHERE IT CANNOT WORK ────────────────────────────────────
+  //
+  // `--background` installs and enables service units. There are none on Windows, so both the offer
+  // and the sentence naming what manages them were wrong there — a reader was told to run a flag that
+  // cannot succeed and given a service manager that is not on the machine and cannot be put there.
+  // Reported from a real run. Same rule as the engine refusal above: do not name a route this platform
+  // does not have.
+  const manager = backgroundManager();
+  if (manager) {
+    say(`  To get your prompt back instead, stop this and run  ${invoke("start")} --background`);
+    say(`  — same product, managed by ${manager}, and it survives logout.`);
+  } else {
+    say("  There is no background form on this platform: the product runs as long as this window does.");
+    say("  Leave it open and use a second terminal for the commands above.");
+  }
   say("");
 }
+
+/**
+ * What a reader is told when a child this install cannot run without exits.
+ *
+ * QUOTED, NOT POINTED AT. This used to end "its own output above says why" while the parent inherited
+ * the child's stderr and therefore held no copy of it. On one report that output never reached the
+ * reader's terminal at all, so the sentence sent somebody scrolling for a line that was not there —
+ * worse than saying nothing, because it reads as a working instruction.
+ *
+ * An empty tail is reported as an empty tail. A child that exits silently is a finding about the child,
+ * and printing a heading with nothing under it would hide exactly that.
+ *
+ * PURE, and exported, so this can be driven without starting a supervisor — the failure path of a
+ * process manager is the one nobody exercises by hand.
+ */
+export function childExitReport({ name, script, code, signal, tail = [] }) {
+  const how = signal ? `on ${signal}` : `with code ${code}`;
+  const said = tail.length
+    ? `Its last line${tail.length > 1 ? "s" : ""}:\n${tail.map((l) => `    ${l}`).join("\n")}\n`
+    : "It exited without printing anything, which is itself the thing to report.\n";
+  return `\nstart: ${name} (${script}) exited ${how}. Stopping the rest.\n${said}`;
+}

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "66760dc4f4b83293e80c8422e0633cdee2aabb41",
-  "version": "0.2.2"
+  "commit": "3c2277f7fab7452490c86d19802dd60a886a2b06",
+  "version": "0.2.4"
 }

package/demo/README.md

@@ -37,7 +37,7 @@ they are machine output with a fixed shape, described here instead:
   the search policy, the receipts, the pre-delivery lint. These are what the report is assembled from
   and what the audit surfaces read.
 - `<product-id>/run/_records/` — the register records the run actually retrieved, one file per record,
-  named by register and number. Real EUIPO records for a fictional mark.
+  named by register and number. Real Clarivate Compumark records for a fictional mark.
 
 `<product-id>/PROVENANCE.md` says how each run was frozen, what was dropped, and how to regenerate it.
 

package/demo/full-country-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-default",
   "title": "Generic default risk framework",
-  "source_deck": "Generic house default — IP Risk Assessment Framework.pptx (Privileged & Confidential), completed by the reviewing lawyer 2026-08-31; supersedes the 2026-07-05 transcription (doc 50), which was partial",
+  "source_deck": "Cordillera house risk framework, authored in-house and reviewed by counsel; 2026-08-31 revision",
   "entity_label": "the company",
   "bands": [
     {

package/demo/global-preliminary-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-default",
   "title": "Generic default risk framework",
-  "source_deck": "Generic house default — IP Risk Assessment Framework.pptx (Privileged & Confidential), completed by the reviewing lawyer 2026-08-31; supersedes the 2026-07-05 transcription (doc 50), which was partial",
+  "source_deck": "Cordillera house risk framework, authored in-house and reviewed by counsel; 2026-08-31 revision",
   "entity_label": "the company",
   "bands": [
     {

package/demo/knockout-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-triage",
   "title": "House knockout triage ladder (Stage 0)",
-  "source_deck": "Ported from the interactive knockout-searches skill's 5-tier rating system (SKILL.md rating table + calibration rules), doc 50 shape",
+  "source_deck": "Cordillera house triage scale for knockout screening, authored in-house; five rating tiers",
   "entity_label": "the client",
   "bands": [
     {

package/demo/multi-country-focus-search/run/_driver/framework.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "framework_key": "house-default",
   "title": "Generic default risk framework",
-  "source_deck": "Generic house default — IP Risk Assessment Framework.pptx (Privileged & Confidential), completed by the reviewing lawyer 2026-08-31; supersedes the 2026-07-05 transcription (doc 50), which was partial",
+  "source_deck": "Cordillera house risk framework, authored in-house and reviewed by counsel; 2026-08-31 revision",
   "entity_label": "the company",
   "bands": [
     {

package/docs/E2E.md

@@ -45,7 +45,7 @@ CLEAROTRON_DATABASE=corsearch                      # REQUIRED, no default (track
 CORSEARCH_SESSION_KEY=dev-offline                       # the credential preflight wants it set; never fetches under the mock
 CLEAROTRON_SATPROBE_CODESIDE=0                              # the probe dials the provider; a mock run cannot
 CLEAROTRON_BAND_TRUTH_GATE=0                                # the gate evidences bands against the production call ledger
-CLEAROTRON_CUSTOMERS_DIR=                                    # unset ⇒ the in-repo demo customers (aurora/zephyr/petcary)
+CLEAROTRON_CUSTOMERS_DIR=                                    # unset ⇒ the demo customer bundled with the repo
 # MCP face (optional): TRADEMARK_MCP_DEV=1 TRADEMARK_MCP_AUTH_DISABLED=1 + loopback host + an ABSOLUTE
 #   CLEAROTRON_ACCESS_FILE=/abs/path/grants.json. All four, or it refuses to start: with auth off and no
 #   grants file every token-less caller resolves to internal read-all across every customer.
@@ -59,8 +59,8 @@ and the refusal prints the absolute path to write.
 Drive one run through the whole spine by hand:
 
 ```bash
-node driver/enqueue.mjs --mark "AURORA PROBE" --classes 9,41 --goods "game software" \
-  --forwarder ops --profile aurora
+node driver/enqueue.mjs --mark "NORTHWIND PROBE" --classes 9,41 --goods "water-quality monitoring software" \
+  --forwarder ops --profile demo-brand-owner
 node driver/runner.mjs            # claims, runs all stages on the mock, publishes, writes the packets
 ls /home/you/trademark-dev/outbox # → <runId>.pending (+ failure/intake packets on the sad paths)
 cat <archived run>/_driver/delivery.json
@@ -75,7 +75,7 @@ outbox packet kind — on a real filesystem with real process boundaries, for fr
 this, from a clean `env -i` shell: enqueue → runner → `DELIVERED (verdict CLEAR)` → archived run dir
 + `<runId>.pending` outbox marker + `_driver/delivery.json` (runId, forwarder, subject,
 `emailBodyHtml`, url, verdict — no profile field; that is `_driver/profile.json` beside it, the run's
-frozen `aurora` demo profile, and the file to open to prove which profile resolved).
+frozen demo profile, and the file to open to prove which profile resolved).
 
 ### Tier 1b — the UI PORTAL (browse the dev instance; develop UI features against it)
 
@@ -105,7 +105,7 @@ so a dev instance beside a live one must be given its own (`PORTAL_PORT`, `PROFI
 silently — each is a proxy to a port, and the port is all it knows. `/recipes/*` is the worse half:
 its save endpoint writes and git-commits into whichever recipe store it reached.
 
-A pass here looks like: index, run report, the aurora customer page and the profile-editor UI all
+A pass here looks like: index, run report, the demo customer page and the profile-editor UI all
 render against the Tier-1 pool; the `/profiles/*` proxy round-trips; traversal and non-loopback binds
 are refused (unit-tested).
 

package/docs/GLOSSARY.md

@@ -0,0 +1,85 @@
+# Glossary
+
+Words this codebase uses in a particular way. They are here because they are already in the tree —
+in file names, comments and test titles — and a contributor meeting one should not have to reverse
+it out of the code. Product vocabulary a client would meet is in [`../README.md`](../README.md); the
+tenant, account and project model is in [`../INSTALL.md`](../INSTALL.md) under "The four things, and
+what contains what".
+
+Nothing here is a rule. Each line says what the word points at, and names the file that owns it.
+
+## The run
+
+**Seat** — one model turn with one job, inside a stage that has several. The common-law grid runs
+halves `a` and `b` and a meaning seat `m`; each has its own model tier and its own ledger, and one
+seat failing is not the stage failing.
+
+**Dispatch** — handing a seat its prompt and waiting for the turn. Recorded per attempt in
+`_driver/<stage>.jsonl`, so a stage that ran three times has three dispatches and one result.
+
+**Matter frame** — what the run understands the request to be: the mark, the goods, the sector, the
+territories. Everything downstream derives from it, and it is told not to widen past the territories
+the job named.
+
+**Blind frame** — a second reading of the raw request that never sees the matter frame. It runs
+beside the investigation as a non-fatal sibling, so a framing mistake shows up as a disagreement
+rather than propagating quietly.
+
+**Feedforward** — the reviewer's flags reaching the corrective pass as data rather than as prose.
+`corrections-feedforward.mjs` decides which flags count as still open.
+
+**Carry-through** — of every subject the run's findings surface, which ones reach none of the
+delivered documents. A finding that is recorded and never carried is the thing this measures.
+
+**Declination** — a record the run enumerated and then decided not to pursue, with the position of
+its reason in `_driver/declination-spec.json`. A declination is a decision, not a gap.
+
+**Refusal** — the product declining rather than failing. `terminalKind: "designed-refusal"`. Nothing
+about a refusal is retried, parked or recovered; the remedy is always the operator's.
+
+## What a run leaves behind
+
+**Ledger** — an append-only record of what was covered, kept so that "unsearched" can never be
+reported as "clean". The coverage ledger appears in the report as prose and as JSON, from one source.
+
+**Receipt** — a record that something happened, kept for observability and deliberately not used as a
+gate. A receipt read as a gate is a Goodhart problem, and the reasoning-integrity receipt says so on
+its own face.
+
+**Register-digest** — the condensed register result a downstream stage reads instead of the raw
+records: the same evidence, at the size a model turn can hold.
+
+**Hit list** — one line per enumerated record and the fate it was given. It is not a read: a record
+can be on the hit list and never opened, and the sign-off condition is about documents actually read.
+
+**Predelivery** — the checks that run after the documents exist and before anyone receives them
+(`predelivery-lint.mjs`, `_driver/predelivery-lint.json`). A failing predelivery withholds the
+artifact; it never annotates it.
+
+**Courier** — delivery as a self-contained packet handed to the integrator. The engine does not send;
+what it produces is carried.
+
+**Drift** — a value that is mirrored in two places by design, and the two disagreeing. The catalogue
+of what is mirrored, and which copy owns it, is in the architecture docs.
+
+## Guards and tests
+
+**Arm** — one `test(...)` block. A file has many; each is named for the property it holds, and a red
+arm is read by its output rather than by its name.
+
+**Plant** — deliberately breaking something to prove a check would catch it. A guard that has never
+been shown failing has not been shown to work, so the hard version plants a NEW instance of the class
+rather than the one the check was written against.
+
+**Contract dictation** — the rule that a contract is stated once and everything else derives from it.
+`contract-dictation.mjs` computes over a corpus; `scripts/contract-dictation-scan.mjs` builds that
+corpus from the tracked tree, so a new authoring layer is caught structurally rather than because
+somebody remembered to list it.
+
+**Assert census** — counting the assertions that never executed. An assertion inside a branch nothing
+reaches is a test that passes and guards nothing (`scripts/unexecuted-asserts.mjs`).
+
+**Authority probe** — asking the live CLI whether it honours a boundary the driver sets, and whether
+the turn survives being refused. CI has no CLI and no subscription, so it can only prove the decision
+is made correctly; whether it is obeyed is a property of the real binary
+(`scripts/authority-boundary-probe.mjs`).

package/docs/PORTAL.md

@@ -133,14 +133,14 @@ rather than quietly opening a passphrase door instead; and local mode refuses a
 `PORTAL_SERVICE_HOST`, because off loopback the passphrase and the session cookie are on the wire in
 clear. Put a TLS-terminating proxy in front if it has to be reachable.
 
-Grants fixture: `{"tenants":{"demo":{"accounts":["aurora"],"users":{"cli@celta.example":["aurora"]}}}}`.
+Grants fixture: `{"tenants":{"demo":{"accounts":["foxglade"],"users":{"cli@celta.example":["foxglade"]}}}}`.
 
 The trigger lane needs the MCP HTTP face and an accounts-scoped ops token; without both, the run step
 reports the trigger lane unwired and the plan step still works. **The face no longer has to be run in
 its dev bypass to provide that**:`TRADEMARK_MCP_AUTH_MODE=token` runs it with a mandatory scoped
 access key and no auth proxy — loopback only, and refused outright alongside
 `TRADEMARK_MCP_AUTH_DISABLED`, which authenticates nobody. Mint the key with
-`mint-token.mjs --scope ops --sub portal --verbs start_run,stop_run --accounts aurora`, or let
+`mint-token.mjs --scope ops --sub portal --verbs start_run,stop_run --accounts foxglade`, or let
 `npx clearotron start` mint one in memory at every start and never write it down.
 
 ## Putting your own login provider in front

package/docs/README.md

@@ -38,6 +38,7 @@ the vendor flags approximate is UNKNOWN, never a number.
 | [`PORTAL.md`](PORTAL.md) | The portal: what it serves, and who sees what |
 | [`CLIENT-MCP.md`](CLIENT-MCP.md) | Publishing a connector your customers sign in to, and how their access is scoped. To connect *your own* app to *your own* runs, use [`../mcp-server/CONNECT.md`](../mcp-server/CONNECT.md) instead |
 | [`E2E.md`](E2E.md) | Proving a deployment works end to end |
+| [`GLOSSARY.md`](GLOSSARY.md) | The words this codebase uses in a particular way — one line each, for a contributor meeting them for the first time |
 | [`SECURITY.md`](SECURITY.md) | The security envelope — what protects what, and where it is enforced in code. To report a vulnerability, use [`../SECURITY.md`](../SECURITY.md) |
 
 Access control is stated once, in [`SECURITY.md`](SECURITY.md): who may see which runs, what an unset
@@ -76,10 +77,11 @@ The other half is structural: it fails on any undeclared identity inside a matte
 which is the half that catches something new. Without the private table the guard runs on synthetic
 sentinels: the machinery is exercised and there is nothing real to find.
 
-**Demo clients are synthetic.** A Generic default (`generic`) plus three inventions — `aurora`
-(gaming), `zephyr` (functional drinks), `petcary` (animal health). They exercise the per-client
-machinery and the test suite. Real client bundles load at runtime from a private store
-(`CLEAROTRON_CUSTOMERS_DIR`) and are never committed here.
+**Demo clients are synthetic.** The published package carries a Generic default (`generic`) and one
+demo brand owner. The repository holds three further invented accounts — gaming, functional drinks and
+animal health — which exercise the per-client machinery and the test suite and are never published.
+Real client bundles load at runtime from a private store (`CLEAROTRON_CUSTOMERS_DIR`) and are never
+committed here.
 
 **Real third-party names are deliberate.** Registers, marketplaces, regulators, research providers and
 the parties to published decisions are named throughout the code, tests and fixtures — as facts about

package/docs/SECURITY.md

@@ -39,6 +39,23 @@ Exactly two roles exist: **staff**, admitted by an email-domain rule (`PORTAL_ST
 created in the guest-list file by whoever administers the box — `npm run grant` is the editor for it —
 never from a browser. The file is re-read per request, so a grant lands without a restart.
 
+**A staff domain is a grant to everyone at that domain, so nothing derives one for you.** Every address
+at a listed domain that gets past the sign-in door is staff, and staff sees every brand owner on the
+instance. The install therefore derives `PORTAL_STAFF_DOMAINS` only from a sign-in address that names no
+second person — the `<account>@localhost` form a single-user machine gets by default. Given a real
+address it states the rule it would create, in the words the People & access screen will later use,
+and refuses to write it: set `PORTAL_STAFF_DOMAINS` yourself, or answer the question `clearotron install`
+asks. A webmail or shared provider is refused outright, because a rule built from one admits the public.
+The People & access screen names the setting the rule came from and the file it is written in, so a
+rule can be traced and undone by whoever finds it.
+
+**That check is on the DERIVATION, not on the value.** A `PORTAL_STAFF_DOMAINS` you set yourself is
+taken as written and never classified: `PORTAL_STAFF_DOMAINS=gmail.com` is accepted, and it admits
+everyone at that provider who gets past the sign-in door. This is deliberate — a value someone typed is
+a decision already taken, and the defect being fixed was a rule created with nobody asked — but it means
+the protection is against the accident and not against the configuration. Read what you set, or set
+nothing and answer the question the install asks.
+
 
 - **On the proxy door**, every HTTP request re-validates a JWT from the fronting auth proxy. The
   proxy is yours to choose — issuer, JWKS URL, claim and header are config

package/docs/architecture/01-product-overview.md

@@ -3,18 +3,30 @@
 > Part of the architecture pack (`docs/architecture/`). The driver's module tree and the headless
 > integrator contract are in [`driver/README.md`](../../driver/README.md).
 
-The clearotron driver turns a plain-language clearance request into a delivered, lawyer-vetted
-preliminary trademark clearance report. One matter in, one decision out — with the investigation,
-the reasoning, the challenge, and the paper trail in between run by deterministic code that treats
-the model as a reasoning step, never as the orchestrator.
+The clearotron driver turns a clearance request into a delivered preliminary trademark clearance
+report. One matter in, one decision out — with the investigation, the reasoning, the challenge, and
+the paper trail in between run by deterministic code that treats the model as a reasoning step,
+never as the orchestrator.
 
 ## What it does
 
-A lawyer forwards a clearance request by email. The system resolves the matter (mark, client,
-scope, deadline), investigates worldwide — trademark registers and the live marketplace, in the
-variations a lawyer would try — reasons the risk in the client's own framework, challenges its own
-draft twice, and delivers a client-formatted report with every factual claim traceable to a fetched
-source record. A lawyer vets the result, then it moves.
+**Who this is for.** Anyone who needs to know whether a name is free to use and is willing to run the
+search themselves: a lawyer, a brand team, or an individual clearing their own mark. You need three
+self-serve accounts: a reasoning CLI, a register, and web research.
+
+**What you get.** Four searches at different depths. A knockout screens up to eight names in minutes.
+A global preliminary, a multi-country focus, or a full country search takes one name deeper, and the
+full country search adds case law. Each delivers a written report with the records behind every
+finding. What you do with it is your call.
+
+The four searches are declared in `driver/products.mjs`, and that declaration is what the rest of the
+system reads: a knockout screens up to eight names and skips case law, and only the full country
+search turns case law on. A knockout takes 5 to 10 minutes; the other three take 1.5 to 2.5 hours.
+
+Under any of them the system resolves the matter (mark, scope, deadline), investigates the trademark
+registers and the live marketplace in the variations a searcher would try, reasons the risk in the
+matter's own framework, challenges its own draft twice, and delivers a report with every factual
+claim traceable to a fetched source record.
 
 The driver is the machine that runs that whole distance. It is **not an agent**: it is a plain
 Node.js process, launched by systemd, that executes a fixed pipeline of stages. Each stage that