clearotron 0.2.4 → 0.3.0-beta.1

package/shared/brand.mjs

@@ -78,6 +78,20 @@ export const BRAND = {
   product: process.env.CLEAROTRON_BRAND_PRODUCT || "Trademark clearance",
 };
 
+/**
+ * The organisation running this installation, or NULL when nobody has named one.
+ *
+ * NOT `BRAND.name`, and the difference is the whole point. That value falls back to the product's own
+ * name so a sentence the product speaks always has something to call itself — "ask Clearotron to enrol
+ * it" reads correctly on an installation nobody has branded. This is the other question: WHO runs this
+ * installation, which on a fresh install has no answer, and answering it with the product's name puts
+ * "Organisation: Clearotron" on the top bar of every install that never set it.
+ *
+ * Null rather than an empty string, so a caller cannot render it by accident. Nothing sets the variable
+ * today; setup gains the question that will.
+ */
+export const ORGANISATION_NAME = process.env.CLEAROTRON_BRAND_NAME?.trim() || null;
+
 /**
  * THE CONFIDENTIALITY POSTURE ON A DELIVERED DOCUMENT — one rule, both report templates.
  *
@@ -614,7 +628,7 @@ export const logoLockup = ({ mark = 30, tag = BRAND.tagline, cls = "" } = {}) =>
 // inherit the SAME staff-auto / client-explicit gating as every other token. `isolation:isolate` + z-index:-1
 // keeps the wash/mark behind content without having to raise every child.
 //
-// THE WORDMARK RENDERS LOWERCASE, AND THE NAME IN PROSE DOES NOT. Owner ruling 2026-08-21, and it is
+// THE WORDMARK RENDERS LOWERCASE, AND THE NAME IN PROSE DOES NOT. Ruling 2026-08-21, and it is
 // the THIRD casing ruling on this name — read the distinction before changing either half:
 //
 //   `.lk-word` (here)   the BRAND MARK. Lowercase — "in the UI, clearotron is lowercase as a brand".

package/shared/bundle-freshness.mjs

@@ -3,7 +3,7 @@
 //
 // bundle-freshness.mjs — is the portal bundle the one its sources would build?
 //
-// MOVED HERE FROM `bin/onboard.mjs` BECAUSE A SECOND READER NEEDS IT (tracker issue 160). `doctor` asked
+// MOVED HERE FROM `bin/onboard.mjs` BECAUSE A SECOND READER NEEDS IT. `doctor` asked
 // this question and answered it well; `/portal/health` asked a narrower one — present or absent — and
 // answered `ui: "built", ok: true` over a bundle `doctor` had just called stale. Two surfaces, two
 // answers, one of them wrong, and the operator has no reason to prefer either.

package/shared/bundle-rebuild.mjs

@@ -4,7 +4,7 @@
 //
 // ── WHY THE PRODUCT DOES THIS RATHER THAN TELLING THE READER TO ─────────────────────────────────────
 //
-// Owner ruling, 2026-09-05: "this is not a question a user should ever face." A packaged install ships
+// Ruling, 2026-09-05: "this is not a question a user should ever face." A packaged install ships
 // the built UI, so an npm install or upgrade replaces the bundle and the sources together and none of
 // this can arise. Only a SOURCE checkout updated by a plain `git pull` can be stale — `portal-ui/dist`
 // is untracked on the public tree, so a pull can never update it — and that reader ran the documented

package/shared/checkout-move.mjs

@@ -2,7 +2,7 @@
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 // checkout-move.mjs — is this command about to repoint the whole deployment at a different tree?
 //
-// ── why this exists (tracker issue 193) ─────────────────────────────────────────────────────────────
+// ── why this exists ─────────────────────────────────────────────────────────────────────────────────
 //
 // `clearotron connect` writes `CLEAROTRON_CHECKOUT_DIR` into the install's env file, set to whatever
 // checkout it happened to be run from. Every shipped unit's `ExecStart` is `${CLEAROTRON_CHECKOUT_DIR}/…`,
@@ -152,7 +152,7 @@ export function describeConflict(posture, move) {
 }
 
 /**
- * Programs executing this product from a tree OTHER than the one the install names (tracker issue 193).
+ * Programs executing this product from a tree OTHER than the one the install names.
  *
  * `doctor` already reports a running program older than the checkout. This is the same question with
  * the more dangerous answer: a process on a DIFFERENT tree keeps working until it restarts, and then

package/shared/client-door.mjs

@@ -2,7 +2,7 @@
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 // client-door.mjs — the client connector's settings, its key, and the revocation of one person's key.
 //
-// ── THE DOOR NOW COMES UP WITH THE PRODUCT (owner ruling 2026-09-03,) ─────────
+// ── THE DOOR NOW COMES UP WITH THE PRODUCT (ruling 2026-09-03,) ─────────
 //
 // There are TWO MCP doors. The ENGINE door (`mcp-server/http-server.mjs`) is what `clearotron start`
 // runs and what the portal's Start button calls; it refuses an account-scoped key outright. The CLIENT
@@ -354,7 +354,7 @@ export function describeDoorState(door, {
  * differ in ONE value — which variable carries that public address — so the composition is one function
  * with that name as a parameter rather than two functions that agree until they do not.
  *
- * Written down after tracker issue 192, where the census found the asymmetry: the client door's
+ * Written down after the census found the asymmetry: the client door's
  * allow-list is composed by the installer and the engine door's was composed by nothing at all, so a
  * hosted operator was asked for a value sitting next to an identical one the product works out. Two
  * authors composing `host:port` in two places is what let them diverge in the first place.
@@ -386,7 +386,7 @@ export function allowedHosts(port, env = {}, { urlName = CLIENT_DOOR_URL_ENV } =
 }
 
 /**
- * The allow-list an existing one should become, once the door's port has moved (tracker issue 197).
+ * The allow-list an existing one should become, once the door's port has moved.
  *
  * The loopback entries are THIS INSTALLER'S and are re-derived from the port; every other host in the
  * list belongs to the operator and is kept. That split is the whole point: a repair about a port must
@@ -522,7 +522,7 @@ export function enablePlan({ env = {}, address, identity, accessFile = null, por
   // identity. Its own preconditions are exactly what this plan has already established — the signing
   // secret, account access on, a loopback host, and an allow-list.
   const settings = {
-    // Written, not required — and this REPLACES whatever was there (tracker issue 193).
+    // Written, not required — and this REPLACES whatever was there.
     //
     // The comment here used to say the opposite: "an installer that already set it keeps its value,
     // because setEnvValue replaces only what this plan names". That reads as a preservation guarantee
@@ -586,7 +586,7 @@ export function enablePlan({ env = {}, address, identity, accessFile = null, por
 /**
  * The change in words, in the tense of the moment the caller is in. ONE author for both.
  *
- * There is no consent prompt — owner ruling 2026-08-31, *"One press does all of it, invisibly… No
+ * There is no consent prompt — ruling 2026-08-31, *"One press does all of it, invisibly… No
  * second step"* — so these sentences are reported AFTER the door is open, or ahead of it under
  * `--dry-run`. What they must never be is two separately written sets that disagree about what was
  * turned on; a stale future-tense sentence printed after the fact is a product describing a change it
@@ -611,7 +611,7 @@ export function describeChange(plan, { applied = false, publicAddress = null, re
   // does not go on to think about who else can reach it, so the claim is made only when it is true, and
   // when it cannot be established it is not made at all. Silence is the safe failure here; a reassuring
   // sentence is not.
-  // ── A PUBLISHED ADDRESS IS NOT AUTOMATICALLY A PUBLIC ONE (tracker issue 130) ────────────────────
+  // ── A PUBLISHED ADDRESS IS NOT AUTOMATICALLY A PUBLIC ONE ────────────────────────────────────────
   //
   // `publicAddress` is whatever the operator put in `CLEAROTRON_CLIENT_MCP_URL`, and a loopback value
   // is a thing an operator does set — it is the address that works for them at the keyboard. The
@@ -739,7 +739,7 @@ export function applyEnablePlan(plan, io) {
 
 // ══ THE LEDGER: what connect issued, as IDs and never as secrets ═════════════
 //
-// Owner ruling, 2026-08-31, verbatim shape: "Say yes. Recording key IDs, never secrets. … Store the
+// Ruling, 2026-08-31, verbatim shape: "Say yes. Recording key IDs, never secrets. … Store the
 // jti beside it and disconnect is: remove the row, add the id to the denylist. No new bookkeeping."
 //
 // The record rides IN THE GRANTS FILE, beside the rows that give the key its reach — one file to read
@@ -799,7 +799,7 @@ export function connectKeyReport(grants, { now = Date.now(), revoked = () => fal
   return { rows, valid: rows.filter((r) => r.state === "valid").length };
 }
 
-// ══ REVOCATION: disconnect is a PERSON, not a service (owner ruling 2026-09-03, Q3) ═══════════════
+// ══ REVOCATION: disconnect is a PERSON, not a service (ruling 2026-09-03, Q3) ═══════════════
 //
 // SUPERSEDED, AND THE OLD SHAPE IS WORTH KNOWING BECAUSE IT WAS COHERENT. Under the 2026-08-31 ruling
 // the door existed only because a reader had asked for it, so its mirror was a teardown: revoke the

package/shared/connect-clients.mjs

@@ -50,8 +50,8 @@
 // Two tables partitioning the same clients on different axes do not merely risk drifting; they had
 // already drifted before either was finished. The page said Codex needs a key address. This table says
 // Codex needs no key at all. On a local install the page's answer resolved to `null`, so the page named
-// a one-line command in its own instructions and then rendered no command — which is tracker issue
-// 1976's defect, sitting inside the page written to answer it.
+// a one-line command in its own instructions and then rendered no command — which is that very
+// defect, sitting inside the page written to answer it.
 //
 // So the browser no longer derives any of this. It is handed resolved rows and renders them. That is not
 // a preference for server-side logic: the install's own filesystem path is not a browser fact, and any
@@ -123,7 +123,7 @@ export const CONNECT_CLIENTS = Object.freeze([
     ],
   },
   {
-    // NOT A SEPARATE PRODUCT (tracker issue 147; owner: "there is no such thing as desktop"). This is
+    // NOT A SEPARATE PRODUCT (decided: there is no such thing as desktop). This is
     // Claude reached the way that runs on the reader's own machine, so it carries Claude's name and says
     // which way it is in the sub-label. The `desktop-json` stdio shape is unchanged — what moved is what
     // a reader is told this is, not how it connects.
@@ -136,7 +136,7 @@ export const CONNECT_CLIENTS = Object.freeze([
 
   // ── Speaks HTTP. Connects from the vendor's own servers. ────────────────────────────────────────
   //
-  // ONE ROW, BECAUSE IT IS ONE APP (tracker issue 147, owner ruling in session: "you know its just ONE
+  // ONE ROW, BECAUSE IT IS ONE APP (ruling in session: "you know its just ONE
   // APP on a laptop which has cowork and code in it and claude is what its called"). `cowork` was a
   // separate row here and is merged in; the sub-label carries where it is met, which is a fact about the
   // reader's screen rather than about our software.
@@ -177,7 +177,7 @@ export const CONNECT_CLIENTS = Object.freeze([
     ],
   },
   {
-    // UNDRIVEN, AND WORDED LIKE IT (tracker issue 148; the owner drives this vendor himself this
+    // UNDRIVEN, AND WORDED LIKE IT (the owner drives this vendor himself this
     // week and the dated stamp appears then). The old second step named "API Key" as the control to
     // choose — the same assertion-from-no-observation that made the cowork row send clients hunting
     // for a box that is not the way in. Two lines and a place to put each is what we actually know.
@@ -201,7 +201,7 @@ export const CONNECT_CLIENTS = Object.freeze([
     // being read by somebody who is not us. Found by driving the four decks; neither instrument could
     // see it, because both ask whether the right row rendered and neither asks whether the sentence reads.
     //
-    // Owner's ruling 2026-09-06, tracker issue 147, option B: this row gets its own line and the approved
+    // Owner's ruling 2026-09-06, option B: this row gets its own line and the approved
     // sentence is left untouched for the three named ones. Option A — renaming the row to "your
     // assistant" — was rejected because it edits a line he approved to repair a line he did not.
     //
@@ -230,7 +230,7 @@ export const CONNECT_CLIENTS = Object.freeze([
  * A stub that restates a wire is a second author for one shape. This is the shape; both callers ask.
  */
 // `sub`, `verifiedOn` and `by` ride only where the ROW carries them, and absent means absent rather than
-// null (tracker issue 147). Two of the three are load-bearing on the page:
+// null. Two of the three are load-bearing on the page:
 //
 //   • `sub` is how one app can appear once per route without two rows claiming to be two products —
 //     "Claude · app, web, and Cowork" and "Claude · app, on this computer" are one product met two ways.

package/shared/connector-signin-probe.mjs

@@ -4,7 +4,7 @@
 //
 // ── why this exists ─────────────────────────────────────────────────────────────
 //
-// Tracker issue 149. Two settings at the identity provider decide whether a remote assistant can sign
+// Two settings at the identity provider decide whether a remote assistant can sign
 // in at all, and this product could see neither. The first — the challenge form — is covered:
 // `shared/mcp-challenge.mjs` reads it out of an unauthenticated response and `doctor` reports it.
 //

package/shared/env-aliases.mjs

@@ -16,7 +16,7 @@
 // install, the install writes the names in force, and the two boxes that predate the rename are
 // REBUILT rather than deployed onto. There is no population left holding the old lines.
 //
-// THAT PREMISE STOPPED BEING TRUE WHEN THE PRODUCT MOVED TO THE REGISTRY (tracker issue 168). A
+// THAT PREMISE STOPPED BEING TRUE WHEN THE PRODUCT MOVED TO THE REGISTRY. A
 // tarball is replaced whole; a published package is UPGRADED, and an upgrade leaves the operator's
 // environment file exactly where it was — so the population the premise says cannot exist is now
 // created by `npm install`. Measured rather than predicted: upgrading the production install across

package/shared/env-local.mjs

@@ -280,7 +280,7 @@ const SHELL_EXPANSION = /\$\{?[A-Za-z_][A-Za-z0-9_]*\}?/;
 /**
  * ── WHERE THIS INSTALL'S `.env` LIVES — ruled, 2026-09-05 ────────────────────────────────────────────
  *
- * `~/.config/clearotron/.env`. The owner's decision, recorded on tracker issue 140, taken from the three
+ * `~/.config/clearotron/.env`. The owner's decision, taken from the three
  * candidates below.
  *
  * WHAT IT FIXES. On a packaged install the wizard wrote `.env` to the package root, which is
@@ -349,7 +349,7 @@ export const LEGACY_ENV_LOCAL_LOCATION = "package-root";
  * what a run can see, and it is the only honest address to give a reader whose units are missing a value.
  *
  * NAMED HERE BECAUSE TWO PLACES NEED IT AND ONE OF THEM IS NOT A CLI. `bin/start.mjs` composed this
- * literal inline while it was the only writer; tracker issue 216 moved the run-configuration refusal to
+ * literal inline while it was the only writer; a later change moved the run-configuration refusal to
  * `driver/runner.mjs`, which must name the same file in the same words. Two `join(homedir(), ".env")`
  * calls are two authorities for one path, and the way that breaks is quiet: a refusal that sends an
  * operator to edit a file the units do not read.
@@ -415,7 +415,7 @@ export function activeEnvPath({ repoRoot = REPO_ROOT, home = homedir(), location
  */
 export function loadEnvLocal({ env = process.env, repoRoot = REPO_ROOT, note = defaultNote,
                               home = homedir(), location = ENV_LOCAL_LOCATION, file = null } = {}) {
-  // ── `file` NAMES A FILE OUTRIGHT, AND EXISTS BECAUSE A CALLER COULD NOT (tracker issue 179) ────────
+  // ── `file` NAMES A FILE OUTRIGHT, AND EXISTS BECAUSE A CALLER COULD NOT ────────────────────────────
   //
   // `readEnvFile(path)` in the wizard means "tell me what THIS file holds". It could only ask by handing
   // over `repoRoot: dirname(path)` and hoping the resolution below landed there — and it did, by
@@ -514,7 +514,7 @@ export const loaded = isCliEntry(process.argv[1]) ? loadEnvLocal() : null;
  *
  * `read` and `absent` are both a yes — absent only means nobody has written it yet, and that IS the file
  * to write. `service-managed`, `opted-out` and `unreadable` are a no, and a no means say nothing rather
- * than guess (tracker issue 200).
+ * than guess.
  */
 export function envFileRead(l = loaded) {
   return l && (l.reason === "read" || l.reason === "absent") ? l.path : null;
@@ -534,6 +534,6 @@ export function envFileRead(l = loaded) {
 //
 // IT WARNS AND RETURNS. There is nothing here that can refuse: the only names it knows are settings
 // whose BEHAVIOUR was deleted, so there is no value to apply wrongly. The renamed install-surface names
-// are not checked for at all — owner ruling, 2026-08-26 — because a machine reaches this code through
+// are not checked for at all — ruling, 2026-08-26 — because a machine reaches this code through
 // the install and the two boxes that predate the rename are rebuilt rather than deployed onto.
 export const aliased = warnRetiredEnv();

package/shared/grants-edit.mjs

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// grants-edit.mjs — the changes a person makes to the grants file: give someone access, and file a new
+// company under its organisation.
+//
+// PURE. Each function takes the parsed grants object and returns a new one; the caller reads the file,
+// applies the change and writes it atomically. One function per change, shared by every writer — the
+// portal's People page, its company creation and `clearotron grant` — so two writers cannot produce two
+// shapes of the same fact. Every result is put through `assertGrantsShape` before it is handed back, so a
+// change that would make the file one the product refuses to load is refused here, before the write.
+import { assertGrantsShape } from "./scope.mjs";
+
+const SWITCHES = ["run", "manage", "everything"];
+
+/**
+ * Give a person access. `points` are `[{ tenant, account? }]`: a whole organisation, or one company that
+ * organisation holds. Points are ADDED; nothing the person already holds is removed, and a company point
+ * inside an organisation they already hold whole is already covered.
+ *
+ * `switches` (`{ run, manage, everything }`) replace the person's entry under `people` when
+ * `setSwitches` is true. A caller that may not change them — the person's access reaches beyond the
+ * caller's own — passes false, and the entry is left exactly as it was.
+ */
+export function withPerson(grants, { email, points = [], switches = {}, setSwitches = true }) {
+  const e = String(email ?? "").trim().toLowerCase();
+  if (!e || e.indexOf("@") <= 0 || e.indexOf("@") !== e.lastIndexOf("@"))
+    throw new Error(`"${email}" is not one email address`);
+  const g = structuredClone(grants ?? { tenants: {} });
+  g.tenants ??= {};
+  for (const { tenant, account = null } of points) {
+    const t = g.tenants[tenant];
+    if (!t) throw new Error(`there is no organisation "${tenant}"`);
+    t.users = { ...(t.users ?? {}) };
+    if (account == null) { t.users[e] = "*"; continue; }
+    if (!(Array.isArray(t.accounts) ? t.accounts : []).includes(account))
+      throw new Error(`organisation "${tenant}" does not hold "${account}"`);
+    const held = t.users[e];
+    if (held === "*") continue;
+    t.users[e] = [...new Set([...(Array.isArray(held) ? held : []), account])];
+  }
+  if (setSwitches) {
+    const entry = { run: switches.run === true, manage: switches.manage === true };
+    if (switches.everything === true) entry.everything = true;
+    g.people = { ...(g.people ?? {}), [e]: entry };
+  }
+  assertGrantsShape(g, "the grants file after this change");
+  return g;
+}
+
+/** File a company under the organisation that holds it. A company belongs to exactly one organisation. */
+export function withCompany(grants, { tenant, account }) {
+  const g = structuredClone(grants ?? { tenants: {} });
+  const t = g.tenants?.[tenant];
+  if (!t) throw new Error(`there is no organisation "${tenant}"`);
+  t.accounts = [...new Set([...(Array.isArray(t.accounts) ? t.accounts : []), account])];
+  assertGrantsShape(g, "the grants file after this change");
+  return g;
+}
+
+/**
+ * Add an organisation. Its key is derived from the name — lowercase, hyphenated — and must not collide
+ * with one that exists. Returns `{ grants, key }`.
+ */
+export function withOrganisation(grants, { name }) {
+  const n = String(name ?? "").trim();
+  if (!n) throw new Error("an organisation needs a name");
+  const key = n.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "organisation";
+  const g = structuredClone(grants ?? { tenants: {} });
+  g.tenants ??= {};
+  if (g.tenants[key]) throw new Error(`there is already an organisation "${key}"`);
+  g.tenants[key] = { name: n, accounts: [], users: {} };
+  assertGrantsShape(g, "the grants file after this change");
+  return { grants: g, key };
+}
+
+export { SWITCHES };

package/shared/install-auth.mjs

@@ -2,7 +2,7 @@
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 // install-auth.mjs — which auth values the units will refuse to start without, on THIS install.
 //
-// ── why this exists (tracker issue 133) ─────────────────────────────────────────────────────────────
+// ── why this exists ─────────────────────────────────────────────────────────────────────────────────
 //
 // From the fresh-user documented-install walk: a reader who does everything the document asks gets two
 // of four units dead. With auth enabled the portal refuses without `CLEAROTRON_OIDC_AUDIENCE` plus

package/shared/listen.mjs

@@ -127,7 +127,7 @@ export function explicitPortRequiredMessage({ what, port, portVar }) {
  *  `portFlag` an optional CLI equivalent, for the entry points that take one.
  */
 /**
- * The first free port at or after `from`, or `null` when nothing in range is free — owner ruling,
+ * The first free port at or after `from`, or `null` when nothing in range is free — ruling,
  * 2026-09-09.
  *
  * WHAT THIS IS FOR AND WHAT IT IS NOT. A collision on a DEFAULT port is this process discovering it
@@ -172,7 +172,7 @@ export function listenErrorMessage(err, { what, host, port, portVar, portFlag =
   // for the units' file, and `clearotron start` — the command that installs those units, so the command
   // that is resolving the ports they will be born with — does not read it. Measured as a stranger on
   // published 0.1.4: the three ports sat in the units' file, the refusal fired, and the only way to see
-  // why was to compare two lists of variable names in a log line (tracker issue 200).
+  // why was to compare two lists of variable names in a log line.
   //
   // The CALLER passes the file, and passes it only when its own loader actually read one. This module
   // cannot know: the same function serves four services booted by units — where naming the CLI's file
@@ -249,7 +249,7 @@ export function listenOrDie(server, {
   // — the env file this process actually read, from `envFileRead()`. Same contract as
   // `portSource` above: null is a caller that has not been taught the question, and its sentence is
   // exactly what it was. Never composed here; a service booted by systemd read no file and must name
-  // none (tracker issue 200).
+  // none.
   portFile = null,
   // — "env" | "default" | null. Null is a caller that has not been taught the question yet and
   // behaves exactly as before; every service in this repo passes it.

package/shared/mcp-challenge.mjs

@@ -77,7 +77,7 @@ export function blockedByAccessChallenge(where, status) {
     + "changed at your identity provider, not here, and NOT repaired by recreating the application "
     + "(recreating it loses this setting and changes the audience, which is two symptoms from one "
     + "cause). "
-    // ── NAME THE SWITCH (tracker issue 149) ──────────────────────────────────────────────────────
+    // ── NAME THE SWITCH ──────────────────────────────────────────────────────────────────────────
     // The rule first and the vendor second, because the identity interface is configuration on
     // purpose: issuer, audience, claim and header are all settings, and a Cloudflare-only remedy
     // re-narrows an interface that was widened deliberately. But a rule with no switch behind it is

package/shared/names-in-force.mjs

@@ -4,7 +4,7 @@
 //
 // Every `CLEAROTRON_*` name this build reads. It exists so the retired-spelling check can name the
 // replacement for an old `PRELIM_*` line rather than only saying the old one is dead — see
-// shared/env-aliases.mjs and tracker issue 168. Re-mint with:
+// shared/env-aliases.mjs. Re-mint with:
 //
 //   node scripts/mint-names-in-force.mjs
 //
@@ -114,6 +114,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_OPENAI_MODEL_JUDGMENT",
   "CLEAROTRON_OPENAI_MODEL_SWEEP",
   "CLEAROTRON_ORDER_PROBE_SEED",
+  "CLEAROTRON_ORGANISATION_NAME",
   "CLEAROTRON_OUTBOX_BACKOFF_BASE_SEC",
   "CLEAROTRON_OUTBOX_BACKOFF_CAP_SEC",
   "CLEAROTRON_OUTBOX_BACKOFF_MAX_RETRIES",

package/shared/onboarding-store.mjs

@@ -14,9 +14,26 @@
 
 import { existsSync } from "node:fs";
 
-/** A refusal is a sentence for the operator, not a stack trace. Every one names what was wrong. */
+/**
+ * A refusal is a sentence for the operator, not a stack trace. Every one names what was wrong.
+ *
+ * IT ALSO CARRIES A CODE AND THE FACTS BEHIND IT, because the same refusal now reaches two very
+ * different readers. The command line's reader typed a flag and is standing in a terminal, so a sentence
+ * naming that flag and the directory it wrote to is exactly right. The browser's reader is a lawyer who
+ * has never seen either, and a sentence mentioning `--platforms` and a filesystem path tells them
+ * nothing they can act on — it tells them they are in the wrong product.
+ *
+ * So the message stays the command line's, and `code` plus `detail` let the other door write its own
+ * sentence from the same facts. A door with no wording for a code falls back to the message, which is
+ * wrong for a browser but never blank — an unworded refusal must not become a silent one.
+ */
 export class Refusal extends Error {
-  constructor(message) { super(message); this.name = "Refusal"; }
+  constructor(message, { code = null, ...detail } = {}) {
+    super(message);
+    this.name = "Refusal";
+    this.code = code;
+    this.detail = detail;
+  }
 }
 
 /**

package/shared/reference-guard-classes.mjs

@@ -249,6 +249,44 @@ export const CLASSES = [
 // a floored line quietly gain a second one. The permissive half of a gate is the dangerous half.
 const EVERY_MATCH = new Map(CLASSES.filter((c) => c.pattern).map((c) => [c.id, new RegExp(c.pattern.source, c.pattern.flags + "g")]));
 
+/**
+ * ── A CITATION THAT WRAPPED IS IN NEITHER LINE ─────────────────────────────────────────────────────
+ *
+ * Every class above reads ONE line, and prose in this tree wraps at a fixed width, so a citation whose
+ * words end one line and whose number begins the next matches nothing. Measured on a real branch: four
+ * citations went in, the census counted four and refused; three came out and the count returned to its
+ * floor with the fourth still in the tree, because that one had wrapped.
+ *
+ * WORSE THAN A MISCOUNT, BECAUSE THE CENSUS IS A RATCHET. The floor only falls, and the check passing is
+ * the statement that the tree grew nothing new — so a wrapped citation is not merely uncounted, it joins
+ * the floor's silence, and nobody looks again because the number did not move.
+ *
+ * A WRAP IS A WRAP ONLY WHEN NEITHER LINE CARRIES ONE ALONE. Joining line N to N+1 also matches when the
+ * whole citation sits on N+1, which would report every ordinary hit a second time as a wrap on the line
+ * above it. `WRAPPED_HEAD` requires line N to END mid-citation, and that is what makes the pair disjoint
+ * from the per-line count rather than overlapping it.
+ *
+ * THE TWO HEAD FORMS ARE COMPLETED BY DIFFERENT THINGS, and collapsing them is the false positive that
+ * matters: a line ending in the bare word `tracker` needs the word `issue` on the next one, while a line
+ * ending in `tracker issue` needs only a number — and without the split, any line ending in `tracker`
+ * followed by a numbered list item reads as a citation.
+ *
+ * ONE DEFINITION. The sweep that removes these reads these same exports; a second detector agreeing today
+ * is two detectors disagreeing later, and while the sweep could see this class and the census could not,
+ * neither could report the disagreement.
+ */
+export const WRAPPED_HEAD = /\btracker\s*$|\btracker issues?\s*$/i;
+export const WRAPPED_TAIL = /^\s*(?:\/\/|#|\*|--)?\s*(?:issues?\s+)?\d+/i;
+
+/** True when `a` ends a citation that `b` completes. PURE. */
+export const wrapsInto = (a, b) => {
+  if (!WRAPPED_HEAD.test(a) || b === undefined) return false;
+  return /\btracker\s*$/i.test(a) ? /^\s*(?:\/\/|#|\*|--)?\s*issues?\s+\d+/i.test(b) : /^\s*(?:\/\/|#|\*|--)?\s*\d+/.test(b);
+};
+
+/** The class a wrapped citation belongs to — the spelled one, because that is what it spells. */
+export const WRAPPED_CLASS = "spelled-citation";
+
 export function offendingClasses(path, line) {
   if (!isScannable(path) || !isProse(path, line)) return [];
   const text = withoutColourValues(withoutLinkTargets(line));
@@ -311,8 +349,12 @@ export function censusOf(files, read) {
     try { text = read(path); } catch { continue; }
     if (text.includes("\0")) continue;                       // a binary blob is not prose
     const counts = CLASSES.map(() => 0);
-    for (const line of text.split("\n")) {
-      for (const { id } of offendingClasses(path, line)) counts[COLUMN.get(id)]++;
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      for (const { id } of offendingClasses(path, lines[i])) counts[COLUMN.get(id)]++;
+      // AND THE PAIR, which no per-line rule can see. Counted on the HEAD line and once: the head ends
+      // mid-citation, so this can never be the same hit the loop above just counted.
+      if (isProse(path, lines[i]) && wrapsInto(lines[i], lines[i + 1])) counts[COLUMN.get(WRAPPED_CLASS)]++;
     }
     const sum = counts.reduce((a, b) => a + b, 0);
     if (sum) { out.files[path] = counts; out.total += sum; }

package/shared/register-selection.mjs

@@ -9,7 +9,7 @@
 // handed in as a PARAMETER by every caller. That was right while the only callers were the wizard and
 // `bin/start.mjs`, which both hold it legitimately.
 //
-// tracker issue 216 added a third and a fourth — the runner's intake wall and the intake doors — and
+// A later change added a third and a fourth — the runner's intake wall and the intake doors — and
 // neither is a CLI. Both would have had to dynamic-import a CLI entry point at call time to read a
 // 44-line data table, and the cycle that trick avoids is not theoretical: a static import in that
 // direction makes `clearotron doctor` exit 13 after printing most of a report, because onboard's