clearotron 0.2.4 → 0.3.0-beta.1

package/bin/onboard.mjs

@@ -70,10 +70,9 @@ import { standFrom } from "../shared/invocation.mjs";   // is this tree one npm
 import { installShim } from "../shared/verb-shim.mjs";   // — the verb goes on PATH
 import { styleFor, banner } from "../shared/tty-style.mjs";   // — weight where the meaning is
 import { bracketAsciiCells, BRAND } from "../shared/brand.mjs";      // F18 — the mark, from the geometry the SVG already uses
-// ONE CLASSIFIER, shared with `bin/start.mjs`. The wizard asks the question; the launcher enforces the
-// answer. Two copies of "what does this domain admit" is a wizard that consents to one rule and a
-// launcher that builds another.
-import { classifyStaffDomain, domainOfEmail, staffDomainRefusal, staffGrantSentence } from "../shared/staff-domain.mjs";
+// THE REFUSALS ABOUT THE SIGN-IN ADDRESS ITSELF, shared with `bin/start.mjs`. Two copies would be a
+// wizard that accepts an address the launcher then sends back.
+import { addressRefusal } from "../shared/staff-domain.mjs";
 import { join, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { delimiter } from "node:path";
@@ -95,14 +94,15 @@ import { resolveAuthMode } from "../driver/engine/auth.mjs";
 import { isInsideCheckout } from "../shared/inside-checkout.mjs";   // — one copy of the rule, and it is testable
 import { packagedBuild as sharedPackagedBuild } from "../shared/packaged-build.mjs";   // — one reader of build-info.json, reachable from the driver
 import { processTable } from "../shared/process-table.mjs";   // — /proc is not the only box
-import { programsFromAnotherCheckout } from "../shared/checkout-move.mjs";   // tracker issue 193
+import { programsFromAnotherCheckout } from "../shared/checkout-move.mjs";
 import { entrypointOf } from "../driver/systemd/install-census.mjs";         // one ExecStart parser
 import { overlayReport, renderOverlayReport } from "../shared/doctrine-overlay.mjs";   // — the doctor reports the overlay
 import { engineInventory, engineMode, ENGINE_MODES } from "../driver/config-inventory.mjs";   //
-import { probeEngineTurn, probeFailureText, PROBE_MODEL, PROBE_TIMEOUT_SEC } from "../driver/engine/probe.mjs";
+import { probeEngineTurn, probeFailureText, PROBE_MODEL, PROBE_TIMEOUT_SEC, engineEnvKeys } from "../driver/engine/probe.mjs";
+import { runRequiredNames, missingRequirements, REGISTER_ENV, ENGINE_ENV } from "../driver/run-requirements.mjs";   // the order-time gate's own question, asked here rather than restated
 import { pinEnv, envFrom } from "../shared/env-aliases.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
-// tracker issues 1861/1882 — one synopsis reader for every verb that prints one.
+// one synopsis reader for every verb that prints one.
 import { usageBlock } from "../shared/usage-block.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
 import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // — ONE KEY=value reader; a second copy would drift from what systemd actually reads
@@ -120,8 +120,8 @@ function readIfPresent(path) {
 
 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
-// WHAT IS READ IS NOT ALWAYS WHERE THE NEXT WRITE GOES. An install configured before the move (tracker
-// issue 159) still has its file at the old path, and the loader still reads it — so every READ here asks
+// WHAT IS READ IS NOT ALWAYS WHERE THE NEXT WRITE GOES. An install configured before the move still
+// has its file at the old path, and the loader still reads it — so every READ here asks
 // the same resolver the loader asks, or this command reports "no configuration" over a file every other
 // command is applying. Writes stay on ENV_PATH: a writer that followed the file backwards would keep an
 // install in the directory npm replaces forever.
@@ -145,7 +145,7 @@ const PROBE_PROVIDERS = has("--probe-providers");
 const PROBE_CONNECTOR = has("--probe-connector");
 
 // ── output ───────────────────────────────────────────────────────────────────────────────────────────
-// WEIGHT WHERE THE MEANING IS (owner ruling 2026-08-31). Every line here used to
+// WEIGHT WHERE THE MEANING IS (ruling 2026-08-31). Every line here used to
 // be the same weight, which is why the passphrase and the coverage reason both disappeared into their
 // surroundings — two defects on that issue that are formatting defects wearing other clothes.
 //
@@ -175,7 +175,7 @@ const blocking = (s) => { blockers.push(s); say(`  ${style.warn("!")} ${s}`); };
 // ── A FOURTH STATE, AND THE COMPOSITE EXIT CONTRACT IT COMPLETES ────────────────────────────────────
 //
 // `inertSetting` is for configuration the operator SET that the build does not read: a retired
-// spelling left behind by an upgrade (tracker issue 168), and anything else of that shape. It needed
+// spelling left behind by an upgrade, and anything else of that shape. It needed
 // its own state because neither existing one is honest about it.
 //
 //   `warn`     prints `!` and keeps rc 0 — but rc 0 is the exact reading that let thirteen ignored
@@ -190,10 +190,10 @@ const blocking = (s) => { blockers.push(s); say(`  ${style.warn("!")} ${s}`); };
 // ── THE CONTRACT, STATED ONCE BECAUSE TWO ISSUES IN ONE BUNDLE BOTH CHANGE IT ───────────────────────
 //
 // rc 1 means: SOMETHING THE OPERATOR SET IS NOT DOING WHAT THEY THINK IT IS DOING.
-//   · `problem`      — set wrongly. A credential present but unusable is this (tracker issue 173): the
+//   · `problem`      — set wrongly. A credential present but unusable is this: the
 //                      file exists, doctor called it enrolled, and the report then disclosed an outage
 //                      that never happened.
-//   · `inertSetting` — set, and not read at all (tracker issue 168).
+//   · `inertSetting` — set, and not read at all.
 // rc 0 means: nothing set is being ignored or misapplied. An ABSENCE stays rc 0 — a fresh machine is
 // not a broken one, and `blocking` exists so an absence that stops the product is still said out loud.
 //
@@ -316,7 +316,7 @@ const prose = (...parts) => { for (const l of wrapProse(parts.join(" "), proseWi
  * @returns {"no-sources"|"unbuilt"|"unversioned"|"guarded"|"tracked-unguarded"|"unmeasured"|"current"|"stale"}
  */
 // `bundleFreshness` and its three readers moved to `shared/bundle-freshness.mjs` when `/portal/health`
-// became a second caller (tracker issue 160): health answered `ui: "built", ok: true` over a tree this
+// became a second caller: health answered `ui: "built", ok: true` over a tree this
 // command refuses at rc 1, because the two surfaces each had their own idea of what a usable bundle is.
 // One definition, both readers, so they cannot disagree again.
 
@@ -565,7 +565,7 @@ export async function offerUsptoSync(dbPath, io, deps = {}) {
 // sales-gated. It used to open with the free tier, and a test asserted that it must — an assertion that
 // argued a case the ADR had already answered. The reasoning is in ADR-0001 and in providers/README.md,
 // which is the canonical statement; this list carries no competing recommendation of its own.
-// ── THE REGISTER SELECTION TABLE MOVED TO `shared/register-selection.mjs` (tracker issue 216) ───────
+// ── THE REGISTER SELECTION TABLE MOVED TO `shared/register-selection.mjs` ───────────────────────────
 //
 // Re-exported here under the name every existing reader uses — this file's own call sites read
 // `PROVIDERS`, and so does the run-requirements arm. It moved because the runner's intake wall and the
@@ -592,40 +592,47 @@ export const AMBIENT_KEYS = [
 const present = (v) => typeof v === "string" && v.trim() !== "";
 
 /**
- * Ask who signs in, and take a real yes for the access rule that address implies.
+ * Ask who signs in, and what their organisation is called.
  *
- * ── WHY THIS QUESTION EXISTS AT ALL ─────────────────────────────────────────────────────────────────
+ * ── WHY THE ADDRESS IS ASKED AT ALL ─────────────────────────────────────────────────────────────────
  *
  * Setup never asked for an address. `clearotron start` therefore took one from `--user`, from
- * `PORTAL_LOCAL_USER`, or from the local account as `<account>@localhost` — and derived a STAFF RULE
- * from everything after its `@`. On the local-account default that rule is `localhost`: one machine,
- * one identity, nothing granted to anyone. Given a real address it is that address's whole domain, and
- * the settings page then reports it back as "Anyone at <domain> — a rule, not a person".
+ * `PORTAL_LOCAL_USER`, or from the local account as `<account>@localhost`. An outside install reached a
+ * state nobody chose that way: an assistant filled a documentation address into the environment file on
+ * the operator's behalf, because this wizard had no prompt for it. So the address is asked for here,
+ * where a person is definitionally present.
  *
- * An outside install reached exactly that state. Nobody typed the address into this wizard, because
- * this wizard had no prompt for it; an assistant filled one into the environment file on the operator's
- * behalf, and the install granted a documentation domain. They read their own settings page and
- * reported it as a back door. They were right to: a grant to a group had been made, by nobody.
+ * WHAT IT NO LONGER DECIDES. The part after its `@` used to decide who was an administrator: everyone at
+ * that domain was staff. That rule is deleted, with the question about granting the domain and the
+ * setting it wrote. The address is the first person on the install — Run, Manage, access to everything —
+ * written as their own entry in the grants file by `clearotron start` (`installerGrants`), and it admits
+ * nobody else whatever its domain.
  *
- * So the address is asked for here, where a person is definitionally present, and the grant it implies
- * is shown in the words the settings page uses BEFORE it is written. `start` no longer guesses: it
- * refuses a rule wider than one machine unless `PORTAL_STAFF_DOMAINS` says so in writing, which is what
- * a yes here writes.
+ * TWO REFUSALS ABOUT THE ADDRESS ITSELF STAY: not a single email address, and a public or reserved
+ * domain (shared/staff-domain.mjs, shared with `clearotron start` so the two refuse the same addresses).
+ *
+ * THE ORGANISATION'S NAME, directly after the address and required. It is the organisation the install
+ * starts with and the label the portal shows for it; `clearotron start` files it in the grants file the
+ * first time that file holds none, and it is renamed there. WRITTEN QUOTED, because the loader reads
+ * `.env` with Node's `parseEnv`, which ends an unquoted value at `#` and trims it — measured: "Café #1
+ * Sàrl" written bare comes back "Café". Quoted it survives whole, except a double quote, which ends the
+ * value, so a name holding one is sent back.
  *
  * THE DEFAULT IS THE LOCAL ACCOUNT AND NOTHING ELSE — not the git author, not the hostname, not a shell
- * variable. An identity that becomes an access rule comes from the person, or from the one source that
+ * variable. The address that becomes the first person comes from the person, or from the one source that
  * cannot name a second person.
  *
- * `io` IS INJECTED for the reason `offerUsptoSync`'s is: the branch that matters is the one where a
- * reader pressed Enter at the grant question and NOTHING must be granted, and closed over a terminal
- * that branch is asserted nowhere. Returns the `.env` keys to write and nothing else.
+ * `io` IS INJECTED for the reason `offerUsptoSync`'s is: the branches that matter are the answers that
+ * must be sent back, and closed over a terminal they are asserted nowhere. Returns the `.env` keys to
+ * write and nothing else.
  */
-export async function askSignIn(io, { localAccount = "user", staffLabel = "Staff", envPath = "" } = {}) {
-  const { askValue, confirm, say = () => {}, ok = () => {}, info = () => {},
-          warn = () => {}, problem = () => {} } = io;
+export async function askSignIn(io, { localAccount = "user" } = {}) {
+  const { askValue, ok = () => {}, problem = () => {} } = io;
   const localDefault = `${localAccount}@localhost`;
-  prose("The portal admits one address on this install, and that address is also what decides who is an",
-        "administrator. Enter accepts the local-account form, which is this machine and nobody else.");
+  prose("The portal admits one address on this install, and that address is the first person on it:",
+        "access to everything, with both permissions — Run clearances and Manage. Enter accepts the",
+        "local-account form, which is this machine and nobody else.");
+  let address;
   for (;;) {
     const typed = String(await askValue("Sign-in address:", { def: localDefault })).trim().toLowerCase();
     if (!typed.includes("@") || typed.indexOf("@") !== typed.lastIndexOf("@")) {
@@ -633,35 +640,27 @@ export async function askSignIn(io, { localAccount = "user", staffLabel = "Staff
         + "so this would sign in and then be denied at the door.");
       continue;
     }
-    const domain = domainOfEmail(typed);
-    const verdict = classifyStaffDomain(domain);
-    if (verdict === "public" || verdict === "reserved") {
-      // The classifier's own sentence, never a second copy: `clearotron start` prints these same words
-      // when it meets the same domain, and two wordings of one refusal is how a reader comes to believe
-      // they have met two different problems.
-      problem(staffDomainRefusal(domain));
+    // The refusal's own sentence, never a second copy: `clearotron start` prints these same words when it
+    // meets the same address, and two wordings of one refusal is how a reader comes to believe they have
+    // met two different problems.
+    const refusal = addressRefusal(typed);
+    if (refusal) { problem(refusal); continue; }
+    address = typed;
+    break;
+  }
+  ok(`${address} — the first person on this install, with access to everything.`);
+  for (;;) {
+    const name = String(await askValue("Your organisation's name:") ?? "").trim();
+    if (!name) {
+      problem("A name is needed here: it is the organisation this install starts with. It can be renamed later.");
       continue;
     }
-    if (verdict === "narrow") {
-      ok(`${typed} — this machine only. No domain rule is written, and nobody else is granted anything.`);
-      return { PORTAL_LOCAL_USER: typed };
+    if (name.includes('"')) {
+      problem(`${name} holds a double quote, and the settings file cannot keep one — it ends the value. Leave it out.`);
+      continue;
     }
-    // `wide`: a real domain, so the grant is a grant. Stated first, in the settings page's own words,
-    // and Enter is NOT a yes — the default is no, because this is the one answer in the wizard that
-    // admits people the reader has never met.
-    say("");
-    warn(`${typed} makes this a rule about ${domain}, not about you.`);
-    say(`    ${staffGrantSentence(domain, { staffLabel })}`);
-    say("");
-    say(`  Everyone at ${domain} who gets past this install's sign-in door would see every brand owner`);
-    say("  on it — every clearance, every report, every configuration. On a laptop that is only you,");
-    say("  because only one address can sign in. Behind a company login it is the whole domain.");
-    say("");
-    if (await confirm(`Grant ${domain} that, and write it down as PORTAL_STAFF_DOMAINS?`, false))
-      return { PORTAL_LOCAL_USER: typed, PORTAL_STAFF_DOMAINS: domain };
-    info(`nothing granted${envPath ? `, and nothing written to ${envPath}` : ""}. ${typed} would sign in `
-      + "and every page would refuse it, because signing in is not being enrolled — so choose the "
-      + "local-account form, or answer yes above.");
+    ok(`${name} — your organisation. \`clearotron start\` files it in the grants file, where it can be renamed.`);
+    return { PORTAL_LOCAL_USER: address, CLEAROTRON_ORGANISATION_NAME: `"${name}"` };
   }
 }
 
@@ -815,7 +814,7 @@ export function engineOptions() {
 export function readEnvFile(path, { home = homedir() } = {}) {
   if (!existsSync(path)) return {};
   const env = {};
-  // NAMED, NOT INFERRED (tracker issue 179). This passed `repoRoot: dirname(path)` and relied on the
+  // NAMED, NOT INFERRED. This passed `repoRoot: dirname(path)` and relied on the
   // loader's resolution happening to land back on the same directory. It did — through the LEGACY
   // fallback, and only while the reader had no `~/.config/clearotron/.env` of their own. With one, this
   // function returned THAT file's contents for any path it was given, including a temporary fixture.
@@ -1128,7 +1127,7 @@ export async function runCheck() {
     warn(`could not tell whether running programs are on the current tree: ${running.detail}`);
   }
 
-  // ── AND THE MORE DANGEROUS ANSWER: A DIFFERENT TREE, NOT AN OLDER ONE (tracker issue 193) ──────────
+  // ── AND THE MORE DANGEROUS ANSWER: A DIFFERENT TREE, NOT AN OLDER ONE ──────────────────────────────
   //
   // The block above asks whether a process predates this checkout's last move. This asks whether it is
   // executing a DIFFERENT checkout entirely, which is what `clearotron connect` used to cause silently
@@ -1231,17 +1230,19 @@ export async function runCheck() {
         home: homedir() })
     : null;
 
-  // ── AND THE DOOR SECTION IS THE THIRD SUCH SECTION (tracker issue 226) ──────────────────────────
+  // ── AND THE DOOR SECTION IS THE THIRD SUCH SECTION ──────────────────────────────────────────────
   //
   // The reading above was hoisted here from further down for this. It used to be resolved BELOW the
   // door check, so the one section making the loudest claim about the running service — "NOBODY can
   // use this portal" — was the one section that could not consult it.
   //
   // MEASURED 2026-09-06 on a healthy packaged install: `doctor` printed that ✗ and exited 1 on a box
-  // where the local user signs in and `GET /portal/api/me` returns `{"role":"staff"}`. The units' file
-  // carries `PORTAL_STAFF_DOMAINS=localhost`, the identity is `<user>@localhost`, and the running
-  // service admits it as staff. This command reads the CLI's own `.env`, where neither that name nor
-  // `PORTAL_AUTH_MODE` appears — so the check was not ignoring the auth mode, it never saw it.
+  // where the local user signs in and `GET /portal/api/me` returned `{"role":"staff"}`. The units' file
+  // carried `PORTAL_STAFF_DOMAINS=localhost` (a staff-domain rule, since deleted), the identity was
+  // `<user>@localhost`, and the running service admitted it as staff. This command read the CLI's own
+  // `.env`, where neither that name nor `PORTAL_AUTH_MODE` appeared — so the check was not ignoring the
+  // auth mode, it never saw it. What admits a person now is their entry in the grants file, and the
+  // units' file is still the only place that names which grants file.
   //
   // The disclosure was already here and one severity too quiet: a `·` saying "what THIS environment
   // implies, not what the running service serves", directly above a `✗` phrased in the present
@@ -1460,7 +1461,13 @@ export async function runCheck() {
       // The auth variables ride this list for the same reason CLEAROTRON_AI does: without them the
       // probe bills the way the AMBIENT environment says rather than the way this .env says, and
       // "proven" would name a lane no run takes.
-      for (const k of ["CLEAROTRON_AI", ...Object.values(ENGINE_BINARIES).flatMap((s) => [s.env, s.authEnv])]) {
+      //
+      // THE CREDENTIALS RIDE IT TOO, and did not. This was a second copy of the list `applyEngineEnv`
+      // applies, and it had dropped the API key and the headless token — so a token kept only in this
+      // install's .env never reached the probe, which then reported the engine signed out while the same
+      // token exported into the shell proved it. `engineEnvKeys` is the probe's own list: the copy that is
+      // filled is now the copy that is applied.
+      for (const k of engineEnvKeys()) {
         const e = effective(k);
         if (e) probeEnv[k] = e.v;
       }
@@ -1516,7 +1523,7 @@ export async function runCheck() {
   }
 
   say("\n  .env");
-  // ── THE FILE MOVED, SO ASK THE SAME QUESTION THE LOADER ASKS (tracker issue 159) ─────────────────
+  // ── THE FILE MOVED, SO ASK THE SAME QUESTION THE LOADER ASKS ─────────────────────────────────────
   //
   // `.env` now resolves to `~/.config/clearotron/.env`, and an install configured before that ruling has
   // it at the old path, where the loader still reads it. Doctor reporting "no .env" over a file every
@@ -1600,7 +1607,7 @@ export async function runCheck() {
       const mod = await import(`../driver/profiles.mjs?doctor=${Date.now()}`);
       const r = mod.profileStoreResolution();
       const where = `profiles resolve from ${r.store}`;
-      // ── ON A HOSTED BOX THE SERVICES' ANSWER COMES FIRST (tracker issue 223) ────────────────────────
+      // ── ON A HOSTED BOX THE SERVICES' ANSWER COMES FIRST ────────────────────────────────────────────
       //
       // One run of this command reported the SAME variable as both set and unset, and concluded a
       // production box was a demo install:
@@ -1672,7 +1679,7 @@ export async function runCheck() {
         // The reader is told they have a customer and not told what they are running on. Both halves
         // wrong from one list.
         //
-        // SINCE 2026-09-08 A FRESH INSTALL RESOLVES `generic` ALONE (owner ruling): nobody should have to
+        // SINCE 2026-09-08 A FRESH INSTALL RESOLVES `generic` ALONE (ruling): nobody should have to
         // clean demo material out of an environment they just created. So the demo branch below no longer
         // fires on a plain install — it fires inside the demo, which asks for its own account. It is kept
         // rather than deleted because it is still reachable, and a reader who meets the demo account
@@ -1727,7 +1734,7 @@ export async function runCheck() {
       // a named disagreement instead of as a tenancy refusal a reader will read as a permissions problem.
       try {
         const cs = await import(`../shared/customer-store.mjs?doctor=${Date.now()}`);
-        // ── ONE ENVIRONMENT ON BOTH SIDES, AND THE LINE SAYS WHICH (tracker issue 223) ────────────────
+        // ── ONE ENVIRONMENT ON BOTH SIDES, AND THE LINE SAYS WHICH ────────────────────────────────────
         //
         // This compared a surface resolved from THIS PROCESS's environment against a roster resolved
         // from this process's module load — so on a hosted box it certified agreement between two
@@ -1744,7 +1751,7 @@ export async function runCheck() {
             + `${split.surface}, runs: ${split.roster}. A brand owner in one and not the other is refused `
             + `by the surface with a tenancy message, which reads as a permissions problem and is not one.`);
         } else {
-          // ── WHAT THIS ✓ CERTIFIES, AND WHAT IT CANNOT (tracker issue 223) ──────────────────────────
+          // ── WHAT THIS ✓ CERTIFIES, AND WHAT IT CANNOT ──────────────────────────────────────────────
           //
           // Both sides derive from `CLEAROTRON_CUSTOMERS_DIR`, which is what 1923 settled — so this
           // cannot catch two environments disagreeing, and reading it as "production is configured"
@@ -1784,7 +1791,7 @@ export async function runCheck() {
   try {
     const report = overlayReport({ baseRoot: config.skillsBaseDir, overlayRoot: config.skillsOverlayDir });
     for (const line of renderOverlayReport(report, { indent: "" })) say(`  ${line}`);
-    // ── AND THE SERVICES MAY HAVE ONE THIS PROCESS CANNOT SEE (tracker issue 223) ───────────────────
+    // ── AND THE SERVICES MAY HAVE ONE THIS PROCESS CANNOT SEE ───────────────────────────────────────
     //
     // `config.skillsOverlayDir` resolves from this process's environment. On a production box that
     // printed "none configured — this install overrides nothing" while CLEAROTRON_INSTRUCTIONS_DIR was
@@ -1869,6 +1876,32 @@ export async function runCheck() {
   // doctor that hangs on a box with no route — so this reports ENROLMENT, and says plainly that a
   // source which is enrolled can still fail at run time. The owner's own report says `CONNECTION_CLOSED`
   // on exactly that case.
+  // ── WILL A SEARCH RUN? — THE ORDER-TIME GATE'S OWN QUESTION, OF THE ENVIRONMENT A RUN WILL HAVE ──
+  //
+  // Every section above reads one requirement from YOUR shell and this command's .env. A search is
+  // refused by a different reader: `orderTimeRefusal`, at order time, against the runner's environment —
+  // a background unit's, on a box that has them. So this command could pass an install the run then
+  // refused: it found `claude` on this shell's PATH while the unit, which has no such PATH, was refused
+  // for an engine path it had never been given. Asking the gate's own authority of the units' environment
+  // is what makes an install this command passes one that can run. `blocking`, not `problem`: an install
+  // that is not configured yet is unfinished rather than broken, and the exit status keeps that contract.
+  say("\n  Will a search run?");
+  if (!serviceKnown) {
+    info("the units' environment could not be read, so what a search would be refused for is NOT checked here — a failure to look is not a clean result");
+  } else {
+    const tables = { registers: PROVIDERS, engines: ENGINE_BINARIES, defaultEngine: DEFAULT_ENGINE_ID };
+    // Two passes: which credentials a run needs depends on the register and the engine it names.
+    const view = {};
+    const fill = (names) => { for (const n of names) { const e = effectiveForService(n); if (e) view[n] = e.v; } };
+    fill([REGISTER_ENV, ENGINE_ENV]);
+    fill(runRequiredNames(view, tables));
+    const { atOrder } = missingRequirements(view, tables);
+    if (atOrder.length) {
+      blocking(`a search is refused until ${atOrder.length === 1 ? "this is" : "these are"} set in ${serviceEnvLabel}: ${atOrder.map((r) => r.name).join(", ")}`);
+      for (const r of atOrder) info(`  ${r.name} — ${r.why}`);
+    } else ok(`nothing a search is refused for at order time is missing from ${serviceEnvLabel}`);
+  }
+
   say("\n  Case law and other capabilities");
   {
     const { caseLawInventory } = await import("../driver/config-inventory.mjs");
@@ -1886,7 +1919,7 @@ export async function runCheck() {
       // other search is unaffected — so it is a `warn`, which says it out loud and leaves the exit code
       // alone. Nothing here can be misconfigured: there is no variable to get wrong.
       //
-      // ── AND A PRESENT-BUT-BROKEN CREDENTIAL IS NEITHER (tracker issue 173) ─────────────────────
+      // ── AND A PRESENT-BUT-BROKEN CREDENTIAL IS NEITHER ─────────────────────────────────────────
       //
       // It is a MISCONFIGURATION: the operator enrolled, the file is there, and it cannot work. That
       // exits non-zero under this command's contract, and it must not be filed under the absence rule
@@ -1991,7 +2024,7 @@ export async function runCheck() {
     blocking(`the portal bundle could not be read — ${e.message} — so whether /portal can render is unknown`);
   }
 
-  // ── THE TRIGGER KEY, AND THE DEADLINE NOBODY WAS COUNTING (tracker issue 161) ────────────────────
+  // ── THE TRIGGER KEY, AND THE DEADLINE NOBODY WAS COUNTING ────────────────────────────────────────
   //
   // A `--background` install stores the portal's trigger key in `~/.env`, the file the units load, and
   // it is minted with a thirty-day life. Nothing counted it down. Thirty days after an install, on a
@@ -2034,6 +2067,60 @@ export async function runCheck() {
       } else {
         ok(`the trigger key is good for ${posture.daysLeft} more day(s), until ${posture.expiresAt}`);
       }
+
+      // ── AND WHICH COMPANIES IT CAN START ────────────────────────────────────────────────────────
+      //
+      // THE THIRD SURFACE, WHICH WAS NEVER WIRED. `triggerCapWarning` exists so the create command, the
+      // portal's boot log and this command cannot say three different things about one gap — its own
+      // comment says "three call sites" — and it had two. The command whose entire job is to report what
+      // a machine is configured for said nothing at all about a cap that decides which companies can be
+      // started. Three is true now, rather than aspirational.
+      //
+      // IT IS `info`, DELIBERATELY, AND THE SENTENCE IS WHY. The portal re-takes its engine credential at
+      // the start of every call, so a stale cap refuses nothing on the ordinary path; the gap bites only
+      // when it CANNOT re-mint. A `problem` here would exit non-zero on installs whose portal re-mints
+      // perfectly well, which is a green install turned red for a refusal that will not happen — and it
+      // would contradict the very sentence it prints. The level is worth revisiting the day the fallback
+      // stops being the exception.
+      //
+      // THE ROSTER IS THE SERVICES', not this process's. A CLI is not started by the units'
+      // EnvironmentFile, and the two answers disagreeing IS a defect this box has produced: a door
+      // resolving the bundled demo roster while the configured store held one more company. Comparing
+      // the units' token against a roster the units never see would report a gap that is not there, or
+      // miss one that is. Which store was read is said, every time.
+      if (posture.readable && posture.accountCapped) {
+        const svcStore = (hosted && serviceKnown) ? (effectiveForService("CLEAROTRON_CUSTOMERS_DIR")?.v || null) : null;
+        let roster = null, why = null;
+        try {
+          const { loadProfiles } = await import(`../driver/profiles.mjs?doctorcap=${Date.now()}`);
+          const { rosterAsItStands } = await import("../driver/company-bundle.mjs");
+          roster = [...rosterAsItStands(svcStore ?? undefined, loadProfiles).keys()];
+        } catch (e) { why = String(e?.message ?? e); }
+
+        // AN EMPTY ROSTER IS NOT A COVERED ONE. `rosterAsItStands` answers an empty Map for a store with
+        // no `generic.json`, and an empty roster leaves NOTHING uncovered — a tick over a could-not-look,
+        // which is the one answer this command must never give.
+        // ALREADY SAID ONCE, AND ONCE IS ENOUGH. A store that refuses to load is reported as a problem by
+        // the roster check a few sections up, in its own words and with its own remedy. Repeating it here
+        // as a second blocker put one fact on the screen three times — the problem, this line, and this
+        // line again in the closing summary — which is how a reader learns to skim the section. Measured
+        // by driving both, with an uncapped token as the control so the duplicate could be told from the
+        // original. What this line adds is the CONSEQUENCE FOR THE CAP, which the roster check does not
+        // know about, so it says that and defers.
+        if (why) {
+          info("whether the trigger key covers them cannot be checked until the roster above loads — not "
+            + "confirmed, and not refused");
+        } else if (!roster.length) {
+          blocking(`the trigger key names a company cap, and no companies could be read from `
+            + `${svcStore ?? "the store this process resolves"} — so nothing here says whether the cap fits`);
+        } else {
+          const { triggerCapGap, triggerCapWarning } = await import("../driver/trigger-cap.mjs");
+          const gap = triggerCapGap({ accounts: posture.accounts, roster });
+          if (gap.uncovered.length) info(triggerCapWarning(gap));
+          else ok(`the trigger key covers all ${roster.length} company(ies) in `
+            + `${svcStore ?? "the store this process resolves"}`);
+        }
+      }
     }
   }
 
@@ -2061,7 +2148,7 @@ export async function runCheck() {
     // The reading is still worth printing — it is what a hand-run process here would use, and it is
     // what `clearotron start` would launch from. It is stated as that, and the sentence below says
     // where the running answer lives.
-    // NAMED, NOT CAVEATED (tracker issue 226). This used to disclaim itself — "what THIS environment
+    // NAMED, NOT CAVEATED. This used to disclaim itself — "what THIS environment
     // implies, not what the running service serves" — directly above a ✗ that asserted a lockout on the
     // live box. The values now come from the file the service actually loads, so the line says which
     // file that was and the verdicts below stand on it.
@@ -2093,68 +2180,66 @@ export async function runCheck() {
     //
     // The door is only half the question. The owner signed into the test portal and every action
     // refused — submitting a search, saving a custom search, loading the Generic defaults — because his
-    // identity was on no staff domain and in no grants row, so it held no accounts. Three symptoms,
-    // one cause, and the product KNEW: portal-service logs a warning at boot naming the identity, both
-    // conditions, both variables and the remedy. It was invisible to everyone who needed it, because
-    // the operator was in a browser and whoever restarted the service checked ports, not the log.
+    // identity held no access in the grants file. Three symptoms, one cause, and the product KNEW:
+    // portal-service logs a warning at boot naming the identity and the remedy. It was invisible to
+    // everyone who needed it, because the operator was in a browser and whoever restarted the service
+    // checked ports, not the log.
     //
-    // ASKED OF `makePrincipal`, the function the door itself uses, so this cannot drift from the
-    // refusal it predicts. A second opinion about who holds access is how a report comes to disagree
-    // with the thing it reports on.
+    // ASKED OF `makePrincipal`, the function the door itself uses, for every address the grants file
+    // names — so this cannot drift from the refusal it predicts. A person is admitted by their own entry
+    // and nothing else: an entry under `people` with access to everything admits with no tenant row at
+    // all, and an entry holding only switches admits nobody, so counting rows in either section would be
+    // a second opinion about who holds access, which is how a report comes to disagree with the thing it
+    // reports on.
     //
-    // OFFLINE, and that is what makes it worth having here: if no staff domain is set AND the grants
-    // file holds no rows, then NO identity can hold access — whoever signs in, whatever the door. That
-    // is knowable from the filesystem, so `--check` can answer it without calling anybody, which is
-    // this command's whole contract.
+    // OFFLINE, and that is what makes it worth having here: if the grants file admits no address, then
+    // NO identity can hold access — whoever signs in, whatever the door. That is knowable from the
+    // filesystem, so `--check` can answer it without calling anybody, which is this command's whole
+    // contract.
     try {
       const { makePrincipal } = await import("../driver/portal-access.mjs");
-      // ASKED OF THE SERVICE'S OWN ENVIRONMENT (tracker issue 226). Reading this command's file here is
-      // what produced a hard ✗ claiming nobody could use a portal that was admitting its operator as
-      // staff on every request.
-      const staffDomains = String(effectiveForService("PORTAL_STAFF_DOMAINS")?.v ?? "")
-        .split(",").map((d) => d.trim()).filter(Boolean);
+      // ASKED OF THE SERVICE'S OWN ENVIRONMENT. Reading this command's file here is what produced a hard
+      // ✗ claiming nobody could use a portal that was admitting its operator on every request.
       const grantsFile = effectiveForService("CLEAROTRON_ACCESS_FILE")?.v ?? "";
       let grants = null, unreadable = null;
       if (grantsFile) {
         try { grants = JSON.parse(readFileSync(grantsFile, "utf8")); }
         catch (e) { unreadable = String(e?.message ?? e).slice(0, 120); }
       }
-      const rows = Object.values(grants?.tenants ?? {})
-        .reduce((n, t) => n + Object.keys(t?.users ?? {}).length, 0);
+      const named = new Set([...Object.keys(grants?.people ?? {}),
+        ...Object.values(grants?.tenants ?? {}).flatMap((t) => Object.keys(t?.users ?? {}))]);
+      const admitted = [...named].filter((address) => makePrincipal({ email: address, grants }));
 
-      // A FAILURE TO LOOK IS NOT A LOCKOUT (tracker issue 226). On a hosted box whose unit environment
+      // A FAILURE TO LOOK IS NOT A LOCKOUT. On a hosted box whose unit environment
       // could not be read, every name above resolves empty — which is indistinguishable from a box that
       // has genuinely configured nothing, and would print the loudest ✗ in this command on no evidence.
       if (!serviceKnown) {
         info("who may use this portal is not judged here: the units' environment could not be read, so a "
-          + "staff domain or a guest list configured there would be invisible to this check");
+          + "grants file configured there would be invisible to this check");
       } else if (unreadable) {
         problem(`the guest list at ${grantsFile} could not be read (${unreadable}) — the portal refuses `
           + `every request while that is true, and this is a failure to look rather than an empty list`);
-      } else if (!staffDomains.length && !rows) {
+      } else if (!admitted.length) {
         // PRESENT-AND-WRONG vs ABSENT. A configured portal that grants nobody is wrong: every page
         // refuses and the symptom reads as a broken login. A box that has configured neither is a
         // fresh install, which is loud but not a failure — the same rule the rest of this command uses.
         const configured = Boolean(grantsFile) || Boolean(effectiveForService("PORTAL_AUTH_MODE")?.v);
-        const sentence = `NOBODY can use this portal, per ${serviceEnvFile}: no staff domain is set (PORTAL_STAFF_DOMAINS) and `
-          + `the guest list holds no rows${grantsFile ? ` (${grantsFile})` : " (CLEAROTRON_ACCESS_FILE is unset)"}. `
+        const sentence = `NOBODY can use this portal, per ${serviceEnvFile}: the grants file gives nobody access`
+          + `${grantsFile ? ` (${grantsFile})` : " (CLEAROTRON_ACCESS_FILE is unset)"}. `
           + "Any identity that signs in is refused at the door on every page, which reads as a broken "
           + `login rather than as missing access. Fix with \`${invocationPrefix()}clearotron grant add\`, `
-          + "or by setting a staff domain.";
+          + `or give the person who installed an entry under "people" in that file, with "everything": true.`;
         if (configured) problem(sentence); else info(sentence);
       } else {
-        const who = [];
-        if (staffDomains.length) who.push(`${staffDomains.length} staff domain(s): ${staffDomains.join(", ")}`);
-        if (rows) who.push(`${rows} guest-list row(s)`);
-        ok(`somebody can use this portal — ${who.join(", ")}`);
+        ok(`somebody can use this portal — ${admitted.length} address(es) in the grants file have access`);
         // AND THE ONE IDENTITY THIS BOX SIGNS IN, when the local door is what this environment implies.
         // NAMES the address because it is this operator's own, on their own box, in a report they asked
         // for — the same address `clearotron start` prints back at them.
         const localUser = effectiveForService("PORTAL_LOCAL_USER")?.v ?? "";
         if (door.shape === "local" && localUser) {
-          if (makePrincipal({ email: localUser, grants, staffDomains })) ok(`  and ${localUser} is one of them`);
-          else problem(`  but ${localUser} — the identity this box's local sign-in produces — is on no staff `
-            + `domain and in no guest-list row, so it signs in and is then refused on every page`);
+          if (makePrincipal({ email: localUser, grants })) ok(`  and ${localUser} is one of them`);
+          else problem(`  but ${localUser} — the identity this box's local sign-in produces — has no access in `
+            + `${grantsFile}, so it signs in and is then refused on every page. Give it an entry under "people" there.`);
         }
       }
     } catch (e) {
@@ -2518,8 +2603,8 @@ export async function runCheck() {
     // rather than beside the unit, because the unit running and the address being reachable are
     // different facts and the second is the one a client depends on.
     const { clientDoorReachability } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
-    // FROM THE FILE THE UNITS LOAD, NOT THE SHELL THIS COMMAND WAS TYPED IN (the tracker issue 226
-    // family, met again here). On a hosted box the published address lives in the units' environment,
+    // FROM THE FILE THE UNITS LOAD, NOT THE SHELL THIS COMMAND WAS TYPED IN (the same family,
+    // met again here). On a hosted box the published address lives in the units' environment,
     // and reading `process.env` reported "no client connector address is published — that is correct
     // for a local install" about a deployment that publishes one. Every verdict below rests on this
     // value, including the audience comparison, so a wrong reading here is not one wrong line.
@@ -2539,7 +2624,7 @@ export async function runCheck() {
         // returns null when the header is absent — a looked-and-none answer, not a did-not-look — and
         // the readers separate those, so a probe that omits the field reads as never-looked rather
         // than silently as "no challenge".
-        // THE REDIRECT TARGET TRAVELS WITH IT (tracker issue 241). This request is already made with
+        // THE REDIRECT TARGET TRAVELS WITH IT. This request is already made with
         // `redirect: "manual"`, so the Location an unauthenticated caller is handed is right here —
         // and it is where Cloudflare Access puts the audience. Reading it from THIS response rather
         // than asking a second time keeps `doctor` to one request per address, and keeps both answers
@@ -2553,7 +2638,7 @@ export async function runCheck() {
     else if (reach.state === "fail") problem(reach.message);
     else info(reach.message);
 
-    // ── AND IS IT THE AUDIENCE THIS INSTALL CHECKS AGAINST? (tracker issue 241) ───────────────────
+    // ── AND IS IT THE AUDIENCE THIS INSTALL CHECKS AGAINST? ───────────────────────────────────────
     //
     // The other half of the recreation trap, and the half with no symptom of its own. Deleting and
     // recreating an Access application changes the audience; the existing warning fires on the
@@ -2577,7 +2662,7 @@ export async function runCheck() {
         // unreachable; repeating it as a second failure teaches the reader that this section
         // double-counts. It still states what was NOT established, which is the whole job.
         else if (v.kind === "could-not-look") info(v.message);
-        // NO ACCESS IN FRONT OF THE CLIENT DOOR IS A POSTURE, NOT A FAULT (owner ruling 2026-09-08).
+        // NO ACCESS IN FRONT OF THE CLIENT DOOR IS A POSTURE, NOT A FAULT (ruling 2026-09-08).
         //
         // This is the CLIENT connector's address, and how a client reaches it is the client's decision:
         // "client access sitting behind OAuth is totally up to a client — plenty might just run it token
@@ -2602,7 +2687,7 @@ export async function runCheck() {
       }
     }
 
-    // ── CAN AN ASSISTANT ACTUALLY SIGN IN? (tracker issue 149, opt-in) ────────────────────────────
+    // ── CAN AN ASSISTANT ACTUALLY SIGN IN? (opt-in) ───────────────────────────────────────────────
     //
     // The check above reads the CHALLENGE FORM, which is the first of two provider settings that decide
     // this. The second — whether the vendor's own redirect address may register — has no symptom a
@@ -2799,7 +2884,7 @@ try {
   // is DERIVED: the engines from ENGINE_BINARIES, the search vendors from the same adapter tables the
   // prompts loop over, each wearing its own table row's where-to-get line. A hand-kept copy here would
   // be the SERPAPI defect again, one screen earlier. Everything is skippable; the list says so.
-  // THE BANNER — once, on entry, named (owner ruling 2026-08-31). Not on every
+  // THE BANNER — once, on entry, named (ruling 2026-08-31). Not on every
   // command: a banner every verb prints is how a product becomes tiresome to use twice. It sits here
   // rather than at the top of main() so that `--check`, which writes nothing and is run repeatedly,
   // does not wear it either.
@@ -3052,8 +3137,8 @@ try {
     // the run has started. So setup will not write an engine it has not exercised — and the menu's last
     // row exists so that refusal always has somewhere to go.
     say("");
-    // — tracker issue 100 point 2, the owner's own words on reading the three lines this replaces:
-    // "wtf does this mean". They named `.env` and "stage failure" and "wearing the shape of a model
+    // — the three lines this replaces were not understood by the reader they were written for.
+    // They named `.env` and "stage failure" and "wearing the shape of a model
     // fault" at a reader who is about to answer yes or no, and every one of those is our vocabulary.
     //
     // THE CHECK IS UNCHANGED AND THE REFUSAL IS UNCHANGED. He valued both, and the issue puts them out
@@ -3162,7 +3247,7 @@ try {
     for (const l of spec.signup) say(`    ${l}`);
     say("");
   }
-  // ── — INSTALL MAY FINISH WITH NO REGISTER. Owner ruling, 2026-08-26 ──────────────────────
+  // ── — INSTALL MAY FINISH WITH NO REGISTER. Ruling, 2026-08-26 ──────────────────────
   //
   // Every row of PROVIDERS declares required credentials, and this prompt had no way out, so a reader
   // with no vendor account could not reach the closing screen at all — the menu offers no "none" row,
@@ -3248,8 +3333,8 @@ try {
     }
   }
   if (registerSelected && !spec.validateEuipo && !spec.uspToLocalKey) {
-    // — tracker issue 100 point 7. The owner asked "why not validate the register provider quickly?" and
-    // the issue sets the fallback where a cheap non-billing call does not exist: say in ONE LINE why it
+    // — decided: validate the register provider quickly where that is cheap, and where it is not,
+    // set the fallback so a check that cannot be made says in ONE LINE why it
     // cannot be checked AND what happens if it is wrong. The first half was already here; the second was
     // not, so a reader was told about our billing scruple and nothing about their own risk.
     //
@@ -3371,7 +3456,7 @@ try {
     ok(`CLEAROTRON_REPORTS_URL=${trimmed}`);
   }
 
-  // 7a-bis ── THE ADDRESS CLIENTS REACH THE CONNECTOR AT (owner ruling 2026-09-03, Q2)
+  // 7a-bis ── THE ADDRESS CLIENTS REACH THE CONNECTOR AT (ruling 2026-09-03, Q2)
   //
   // *"The installer asks once, at install, on the box. It is a deployment setting, never a per-person
   // one. Changing it later is editing that one setting and restarting."*
@@ -3501,21 +3586,18 @@ try {
   say("  fallback — falls through by name, so an empty store is a working install. Your own customers");
   say("  are added here by name; the bundled demo customers never show through into your roster.");
 
-  // 7c ── WHO SIGNS IN, AND WHAT THAT ADDRESS GRANTS
+  // 7c ── WHO SIGNS IN, AND WHAT THEIR ORGANISATION IS CALLED
   //
-  // Setup never asked for an address, so `clearotron start` derived one — and derived a staff-domain
-  // rule from everything after its `@`. The whole reasoning, and the install that granted a
-  // documentation domain to a reader who had never been asked, is on `askSignIn` above.
+  // The address is the first person on the install and the name is its first organisation. The whole
+  // reasoning, including the domain rule this step no longer writes, is on `askSignIn` above.
   section("Who signs in");
   const localAccount = (() => {
     try { return userInfo().username || "user"; } catch { return "user"; }
   })();
-  // ONE CALL SITE. The loop itself lives in `askSignIn` so that the branch that matters — a reader who
-  // pressed Enter at the grant question, and a staff rule that must therefore NOT be written — is
-  // reachable without a terminal. The same seam and the same reason as `offerUsptoSync`.
-  Object.assign(candidate, await askSignIn(
-    { askValue, confirm, say, ok, info, warn, problem },
-    { localAccount, staffLabel: `${BRAND.name} staff`, envPath: ENV_PATH }));
+  // ONE CALL SITE. The loop itself lives in `askSignIn` so that the branches that matter — an address
+  // that must be sent back, a name that is missing — are reachable without a terminal. The same seam
+  // and the same reason as `offerUsptoSync`.
+  Object.assign(candidate, await askSignIn({ askValue, ok, problem }, { localAccount }));
 
   // 8 ── the engine's own preflight over the whole candidate
   //
@@ -3548,7 +3630,7 @@ try {
   // 9 ── write, atomically
   say("\n  Writing configuration");
   // THE DIRECTORY MAY NOT EXIST, and on a fresh machine it does not. `.env` now lives under
-  // `~/.config/clearotron/` (tracker issue 140), which nothing else creates — and the failure without
+  // `~/.config/clearotron/`, which nothing else creates — and the failure without
   // this line lands on the temporary file below, so it reads as a permissions problem writing `.env`
   // rather than a missing folder. Mode 700: the file inside is 600 and holds credentials, so a
   // world-readable directory around it advertises that it is there.
@@ -3577,7 +3659,7 @@ try {
   //
   // The owner was given a command, typed it from his home directory, and got npm's error rather than
   // ours: `npx` resolves a local package by walking UP from the current directory, so every command
-  // this product prints worked only where the reader happened to be standing. Owner ruling 2026-08-26:
+  // this product prints worked only where the reader happened to be standing. Ruling 2026-08-26:
   // put the verb on PATH, as a per-user shim — `npm link` wants write access to `/usr` and refuses
   // without root, which is why stopped at teaching the product to print `npx`.
   //
@@ -3657,7 +3739,7 @@ try {
   say(`  ${style.dim(`\`${invocationPrefix()}clearotron run --job examples/job.euipo.json\` runs a first real clearance on the EU register.`)}`);
   say(`  ${style.dim("Each still works the old way too — `npm start`, `npm run example`, `node driver/pipeline.mjs`.")}\n`);
 
-  // WHY THOSE LINES LOOK THE WAY THEY DO, when they are not the bare verb (Refs tracker issue 1916).
+  // WHY THOSE LINES LOOK THE WAY THEY DO, when they are not the bare verb.
   //
   // A login profile adds `~/.local/bin` to PATH only if the directory existed when the shell started,
   // so the shim written seconds ago is usually absent from THIS terminal's PATH and arrives at the next