clearotron 0.2.2 → 0.2.3

package/bin/start.mjs

@@ -130,6 +130,9 @@ 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";
 
 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 +369,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 +382,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 +836,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 +875,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`);
@@ -1574,10 +1668,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 +1714,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) => {
@@ -1861,3 +1985,25 @@ if (isMain) {
   say("  — same product, managed by systemd, and it survives logout.");
   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": "5c8eca66a5f226dde9e1d01affd63da4eda61bbd",
+  "version": "0.2.3"
 }

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/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

@@ -76,10 +76,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/04-configuration-reference.md

@@ -283,6 +283,8 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 |---|---|---|
 | `DEMO_PORT` | `18900` | Port `npx clearotron demo` serves the replayed report on. `--port` overrides it. |
 | `CLEAROTRON_DEMO` | unset | `1` puts this install in the DEMO posture. **Ordering is real**: the four products are listed and orderable, the form, the plan and the confirmation are the product's own, and the confirmation resolves to a finished report that already exists rather than dispatching — no engine turn, no register call, no queue entry, no run directory (owner ruling 2026-08-31, superseding the greyed-control ruling of the same day). A product the demo carries no finished report for refuses and names which one. It also re-aims two boot warnings written for an operator of a real deployment at the visitor who is not one, from one place (`driver/demo-posture.mjs`). **Set by `npx clearotron demo`, not by an operator** — it is passed explicitly to the two processes that have a reason to know (the portal and the MCP door; the worker is not told, because a demo never queues anything for it to drain), and those run with `CLEAROTRON_NO_ENV_FILE=1`, so a stray `.env` can neither put a live install into demo mode nor take a demo out of one. Anything but the literal `1` is not a demo. Replaces `PORTAL_DEMO`, which named only one of the processes that has to know. |
+| `CLEAROTRON_TEST_FIXTURE_PROFILES` | unset | `1` makes the profile loader return the three suite fixtures, which are refused from every roster otherwise. Set by `scripts/test-run.mjs`, never by an operator; an explicit `includeTestFixtures` argument beats it. Effect class `harness`; the full contract is its row in `.env.example`. |
+| `CLEAROTRON_DEMO_PROFILES` | unset | `1` makes the profile loader return the bundled demo account, which a fresh install does not resolve (owner ruling 2026-09-08). Set by `clearotron demo`, `start --demo` and the suite runner, never by an operator. The gate is on the bundled layer, so a deployment's own configured store keeps its `demoData` accounts either way. Effect class `harness`; the full contract is its row in `.env.example`. |
 | `PORTAL_LOCAL_CREDENTIAL` | `~/.cordillera/portal-local-credential.json` | Where local sign-in keeps its passphrase DIGEST. `npx clearotron demo` points it inside the demo's own base directory, so a demo mints its own passphrase instead of inheriting a digest minted for another address — and removing the demo stays one `rm -rf`. |
 | `PORTAL_LOCAL_PASSPHRASE` | unset | **NEVER set this in a file.** An internal one-shot handoff, not an operator control: on a first FOREGROUND start the supervisor mints the passphrase and hands it to the portal it spawns *at the spawn call*, so the closing summary can print the value beside the address rather than sending a first-time reader back into eleven startup log lines for the one value in this product that cannot be read back. It is deliberately absent from the composed child environments, because that composition is what `--background` writes into the units' env file — a passphrase there would be a permanent plaintext copy on disk and the product's own sentence, "it is stored only as a digest", would stop being true. Setting it in any env file recreates exactly that. Lost passphrase: `clearotron passphrase --reset`. |
 | `PORTAL_URL` | `http://127.0.0.1:18802`, or built from `PORTAL_SERVICE_HOST`/`PORTAL_SERVICE_PORT` | Where the deploy tick's live-surface check expects to reach the portal. |

package/docs/architecture/05-config-governance.md

@@ -303,6 +303,20 @@ Staff MCP: `TRADEMARK_MCP_HTTP_PORT` (18790), `TRADEMARK_MCP_HTTP_HOST`,
 `TRADEMARK_MCP_EMAIL_CLAIM`, `TRADEMARK_MCP_AUTH_HEADER`, `TRADEMARK_MCP_URL`,
 `TRADEMARK_MCP_AUTH_MODE` (see below),
 `TRADEMARK_MCP_AUTH_DISABLED` / `TRADEMARK_MCP_DEV` (dev seams — never set in prod).
+
+`TRADEMARK_MCP_KEY_SOCKET` is the local key door, and it is a PATH rather than a port on purpose. This
+interface serves two populations that authenticate differently: people arriving through a tunnel, who
+prove themselves with a proxy identity, and programs on the same machine holding a scoped access key,
+which can never produce one. "Only accept a key from loopback" does not separate them — the tunnel daemon
+runs on the same machine, so a request forwarded from the internet and one from the local portal arrive
+with the same peer address. A tunnel forwards to a port and cannot reach a unix socket, so the transport
+is the discriminator and the two doors are separate objects with opposite rules.
+
+Unset means no key door, and a deployment gets exactly the door it had before. The socket is created
+`0660` — owner and group only — with the mode set after `listen`, because `listen` creates the file and
+the umask decides what it starts as. It refuses to open at all with no grants file, alongside
+`TRADEMARK_MCP_AUTH_DISABLED`, or when `TRADEMARK_MCP_AUTH_MODE` is `token`: that mode makes the NETWORK
+door take a key too, which is the thing this exists to prevent. Read by `mcp-server/key-socket.mjs`.
 Client MCP: `CLIENT_MCP_HTTP_PORT` (code default 18811, matching the deployed unit; it was 18795,
 which collided with a co-hosted warm-MCP block, so keep any unit override that names a port),
 `CLIENT_MCP_HTTP_HOST`, `CLIENT_MCP_ALLOWED_HOSTS`,

package/docs/architecture/05-customer-profiles.md

@@ -3,8 +3,8 @@
 > 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).
 > This chapter describes the profile *mechanism*. Real customer bundles load from an external store
-> via `CLEAROTRON_CUSTOMERS_DIR` and no customer is named here; the repository ships `generic` plus the
-> synthetic demo customers `aurora`, `zephyr` and `petcary` — see
+> via `CLEAROTRON_CUSTOMERS_DIR` and no customer is named here; the package ships `generic` and the demo
+> brand owner, and the repository holds three further synthetic profiles for the test suite — see
 > [`driver/profiles/`](../../driver/profiles/).
 
 One engine, never forked — three layers. The reasoning core is shared by every client; the client

package/docs/configuration.md

@@ -115,9 +115,10 @@ under that framework. Absent, the generic set applies.
 
 ## 3. Client profiles
 
-One JSON file per client under [`driver/profiles/`](../driver/profiles/). Four ship as working
-examples: `generic` (the Generic default) plus three synthetic demo clients — `aurora` (gaming),
-`zephyr` (functional drinks) and `petcary` (animal health).
+One JSON file per client under [`driver/profiles/`](../driver/profiles/). Two are published as working
+examples: `generic` (the Generic default) and the demo brand owner. Three further synthetic profiles —
+gaming, functional drinks and animal health — exist in the repository for the test suite and are left
+out of the package.
 
 A job picks its profile by **forwarding domain** — `matchDomains[]`, exact host or dot-suffix. The
 applicant named in a request never selects a profile. Resolution happens once at run start and is

package/driver/CHANGELOG.md

@@ -1,5 +1,61 @@
 # clearotron-driver
 
+## 0.2.3
+
+### Patch Changes
+
+- 54ea03a: Fixed: The configuration check no longer reports a problem when the client connector's address is reached with its own token. Putting a single sign-on front before it is the client's choice, and running it token-based is supported. The check still says the sign-in audience was not compared against that address, so it never implies the two agree.
+- 4b6be02: Fixed: A bundled risk framework now states where it came from in words a customer can read. The note used to carry a confidentiality marking, a filename for a document not included, an internal reference number and revision history. It says whose framework it is, who stands behind it and which revision, and nothing else.
+- 63f916c: Fixed: A fresh install's brand-owner list now offers Generic and, with the demo, the demo account. It offered three of our test accounts as well, on the install route that clones the repository.
+- 5d12baa: Fixed: A run record now says which version of the engine's command-line tool served it. A change in results can be traced to a tool upgrade rather than guessed at.
+  
+  Fixed: A version the tool could not report is recorded as unreadable. An absent field could not be told apart from a probe that never ran.
+- 888de5d: Fixed: The deployment check now says whether each scheduled job's timer is still armed. A timer-driven service reads "inactive" between runs and when its timer has been stopped. So a check that asked only about the service could report nothing wrong while the scheduled work had quietly stopped happening.
+- 3a75e22: Fixed: A supplementary memo now succeeds on its first attempt. It cost two turns instead of one, and left a retried-stage mark on a report that had been delivered cleanly.
+  
+  Fixed: A supplementary memo states the rating framework it was reasoned under. A report assessed under a customer's own framework said so; a memo written from it did not.
+- fe22384: Fixed: Installing on a Node version the engine cannot run on now stops at once. It names the version you have, the version needed, and the command that fixes it. Before, the install finished and the first US register search failed with an error that never mentioned Node. The supported floor is Node 22.13 or newer.
+- 74b2cdd: Fixed: Setup now asks which address signs in, instead of turning it into an access rule covering everyone who shares its email domain.
+  
+  For operators: The People & access page now names the setting behind a staff rule, and the file to edit to undo it.
+- 9053919: Fixed: Five things a first-time reader could not act on.
+  
+  A screen that needs a brand owner chosen no longer points at the top left when the menu is collapsed and there is nothing there.
+  
+  The profile editor's Save button now states the one thing that is blocking it. That reason was always there, but it looked the same as the states where nothing is wrong.
+  
+  The default jurisdictions field now says what it does with what you type. Entries are checked against the list and kept, never refused. A region counts as one entry.
+  
+  The trademark categories field explains what those numbers are, with examples, before naming the standard they come from.
+  
+  The row of coloured ratings under "Risk framework in force" now says it belongs to that framework. It used to read as a list of several frameworks. Both editors say it the same way.
+- fe22384: For operators: Clearotron runs on Node 22.13 or newer again, down from 22.19, because its HTTP client moves back to version 7. Anyone who upgraded Node for the last release has nothing to undo.
+- bb899a7: New: A screening report now leads with the read. Each conflict shows its name, band, source and a one-sentence verdict. The paragraph arguing that verdict is one click away. Register filings appear as conflicts only where the reviewer rated them above the lowest band; the rest stay in the filings table.
+  
+  New: What was asked is now at the top of a screening report, with any question about whether it was the right thing to ask. Both used to sit at the bottom.
+  
+  New: The long per-name assessment now opens from the read. The engine has always written it and the page never showed it.
+  
+  New: Register counts say what they counted in their column headers. Territories are named rather than printed as two-letter codes.
+  
+  New: The lines a reader meets before opening anything are written in plain language. That is the summary, the basis line, each conflict's one sentence and the reviewer's notes. Legal vocabulary stays where the detail is.
+  
+  Fixed: Reviewer notes no longer appear on a screening report exported to PDF. They are for the reviewing lawyer, and a report forwarded to a client used to carry them.
+- 2a812d6: Fixed: The New clearance screen now has a **Start a search** button. The button that ran a search used to say "Review clearance", and people could not tell it was the way to begin.
+  
+  Fixed: When a search cannot start yet, the screen says what is still missing, both on the form and beside the button. It used to grey the button out and give no reason at all.
+  
+  Fixed: **Save as search** now confirms the save beside the button that was pressed, names what was saved, and links to it. It gave no sign at the point of the click.
+  
+  Fixed: The unsaved-changes warning no longer fires on a search you have just saved. It compared the form against a blank one and nothing ever reset it.
+  
+  Fixed: The message shown when no search engine is attached now names the setup command for the way you installed. It used to name the one that only works in a copy of the source.
+- 58af0b7: Fixed: The settings page no longer shows the engine as healthy when the engine program cannot be found.
+  
+  That page reports which engine is configured. The New clearance screen reports whether a search can start right now. When those two readings disagreed, neither screen said so.
+  
+  An install could therefore show a green engine while no search would start, and nothing explained the gap. The settings page now names the disagreement and says what to do about it. Running `clearotron doctor` reports the same thing in the same words.
+
 ## 0.2.2
 
 ### Patch Changes

package/driver/common-law-receipts.mjs

@@ -154,7 +154,7 @@ export function countMatrixCells(findingsContent) {
  * "丝绸与铁 / 席尔克": each alternate is its own search term with its own grid — the copper-conduit worker
  * keyed the split forms with full receipts while the validator demanded the compound key, 2026-06-12);
  * or WORD-BOUNDARY substring coverage (a fully-receipted variant covers a LONGER variant containing it
- * as a whole-word phrase — "Aurora Legends II: Oak & Ember" ⊃ "Oak & Ember"; a marketplace phrase
+ * as a whole-word phrase — "Foxglade Legends II: Oak & Ember" ⊃ "Oak & Ember"; a marketplace phrase
  * search for the short form surfaces every listing of the long form. Mid-word containment does NOT
  * count: "venzyy" ⊅ "venzy" — storefront search tokenizes, a doubled-letter variant is its own term).
  */

package/driver/config-staleness.mjs

@@ -5,7 +5,7 @@
 // ── THE OUTCOME THIS EXISTS TO STOP ─────────────────────────────────────────────────────────────────
 //
 // After the F41 repair the owner restarted the worker, as instructed, and refreshed the portal. It
-// showed the BUNDLED DEMO ROSTER — aurora, petcary, zephyr — and not his own account.
+// showed the BUNDLED DEMO ROSTER and not his own account.
 //
 //     ~/.env repaired   10:51:16
 //     worker            10:51:21   ← new config

package/driver/dev-portal.mjs

@@ -301,7 +301,7 @@ async function loadOutbox(){const r=await(await fetch("/dev/outbox")).json();
 let REG=null;
 const esc=(s)=>String(s??"").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;");
 async function loadSearches(){
- const cust=$("#s_cust").value.trim()||"aurora";
+ const cust=$("#s_cust").value.trim()||"demo-brand-owner";
  try{
   const all=await(await fetch("/recipes")).json();
   if(all.error){$("#searches").innerHTML='<span class="err">'+esc(all.error)+'</span>';return;}
@@ -320,7 +320,7 @@ async function loadSearches(){
 function useProduct(k){const f=$("#f");f.product.value=k;$("#f_recipe").value="";f.mark.focus();}
 function useRecipe(cust,slug){const f=$("#f");f.product.value="";$("#f_recipe").value=slug;f.profile.value=cust;f.mark.focus();}
 async function composeSubmit(save){
- const cust=$("#s_cust").value.trim()||"aurora";
+ const cust=$("#s_cust").value.trim()||"demo-brand-owner";
  const fd=new FormData($("#sf"));
  const recipe={label:(fd.get("label")||"").trim(),base:fd.get("base")};
  if(fd.get("registerProbe")!=null)recipe.components={registerProbe:true};

package/driver/driver.config.mjs

@@ -248,7 +248,7 @@ export const config = {
   // 2026-07-19: these were joined against DRIVER_DIR, so the driver read framework manifests out of
   // its BUNDLED driver/skills while CLEAROTRON_INSTRUCTIONS_DIR pointed the agent at the config store. A
   // customer whose framework lives only in the config store therefore hard-failed at attachFramework
-  // with `framework_manifest_missing` — the first Aurora Interactive run died there before any stage ran.
+  // with `framework_manifest_missing` — a test account's first run died there before any stage ran.
   get skillsRoot() { return dirname(this.skillsDir); },
 
   // ── Per-agent paths ───────────────────────────────────────────────────────