clearotron 0.2.4 → 0.3.0-beta.1

package/bin/disconnect.mjs

@@ -11,11 +11,11 @@
 // is listening. The person most likely to believe "I turned it off" is the one who just stopped the
 // service.
 //
-// Owner ruling, 2026-08-31: record key IDs never secrets; the id goes to the denylist; the record is
+// Ruling, 2026-08-31: record key IDs never secrets; the id goes to the denylist; the record is
 // struck. REVOCATION COMES FIRST in the apply order — if this dies halfway, the half that must already
 // have happened is the credential being dead.
 //
-// ── WHAT THIS VERB STOPPED DOING ON 2026-09-03 (owner ruling, Q3) ─────────────
+// ── WHAT THIS VERB STOPPED DOING ON 2026-09-03 (ruling, Q3) ─────────────
 //
 // It used to stop and REMOVE the unit, and turn `CLIENT_MCP_ACCOUNT_ACCESS` back off. Both were right
 // while the door existed only because a reader had asked for it. The door now comes up with the
@@ -257,7 +257,7 @@ async function cutEveryoneOff({ dryRun }) {
   return 0;
 }
 
-// THE DISPATCH RUNS ONLY WHEN THIS FILE IS THE COMMAND (tracker issue 183). Importing a verb to reach
+// THE DISPATCH RUNS ONLY WHEN THIS FILE IS THE COMMAND. Importing a verb to reach
 // something inside it must read a module, not start a command — `bin/connect.mjs` opened its interactive
 // prompt and hung a suite when an arm imported it for one message helper.
 //

package/bin/example.mjs

@@ -50,7 +50,7 @@ import { isFrozen, demoChildren, publishSource } from "../driver/demo-container.
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 
-import { usageBlock } from "../shared/usage-block.mjs";   // tracker issues 1861/1882
+import { usageBlock } from "../shared/usage-block.mjs";
 const argv = process.argv.slice(2);
 const flag = (n, d = null) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : d; };
 const has = (n) => argv.includes(n);
@@ -65,11 +65,11 @@ if (has("--help") || has("-h")) {
   //
   // Until now the flag was discoverable only by getting it wrong: `--help` listed --run-dir, --base,
   // --port and --no-open and stopped, so three of the four shipped demos were invisible from the
-  // command written to give somebody their first look (tracker issue 201).
+  // command written to give somebody their first look.
   const shipped = demoChildren(join(REPO, "demo"));
   if (shipped.length) {
     console.log(`\n  --product takes one of:`);
-    // NO "DEFAULT" MARKER (tracker issue 277). This printed "(the default, when --product is not given)"
+    // NO "DEFAULT" MARKER. This printed "(the default, when --product is not given)"
     // beside the first id, and kept printing it after the default became ALL of them — so `--help` taught
     // a reader the exact belief the change removed, in the command it was reported against.
     for (const id of shipped) console.log(`    ${id}`);
@@ -110,7 +110,7 @@ const DEMO_ROOT = join(REPO, "demo");
 const wanted = flag("--product");
 const children = demoChildren(DEMO_ROOT);
 
-// ── ALL OF THEM, UNLESS THE CALLER NARROWED IT (tracker issue 277) ──────────────────────────────────
+// ── ALL OF THEM, UNLESS THE CALLER NARROWED IT ──────────────────────────────────────────────────────
 //
 // This used to replay `children[0]` and stop. The package ships one finished report per product, and a
 // first-time reader met one of them with nothing on screen saying the other three existed — so three
@@ -129,8 +129,8 @@ const sampleDirs = flag("--run-dir")
 // the container itself is what it looks at, which is what it always did when `demo/` was empty.
 const sampleDir = sampleDirs[0] ?? resolve(DEMO_ROOT);
 if (!sampleDirs.length || !isFrozen(sampleDir)) {
-  // AN ABSENCE IS A FINDING, AND IT NAMES WHAT IT LOOKED AT. This exits 1 and always has; tracker issue
-  // 2193 reported it exiting 0, which did not reproduce at v0.1.0 or at main's tip. An arm pins it.
+  // AN ABSENCE IS A FINDING, AND IT NAMES WHAT IT LOOKED AT. This exits 1 and always has; a report of
+  // it exiting 0 did not reproduce at v0.1.0 or at main's tip. An arm pins it.
   die(
     `demo: no frozen demo at ${sampleDir}`,
     "",
@@ -231,7 +231,7 @@ console.log(`  reports folder:  ${poolRoot}\n`);
 mkdirSync(poolRoot, { recursive: true });
 const { republishRun } = await import(pathToFileURL(join(REPO, "driver", "publish", "report-registry.mjs")).href);
 
-// ── ONE FAILURE MUST NOT COST THE OTHERS, AND MUST NOT BE A QUIET COUNT (tracker issue 277) ─────────
+// ── ONE FAILURE MUST NOT COST THE OTHERS, AND MUST NOT BE A QUIET COUNT ─────────────────────────────
 //
 // Publishing stopped at the first error, which was right when there was one demo and is wrong now: a
 // reader whose knockout capture is unreadable should still get the other three, and should be TOLD which

package/bin/framework-preflight.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// 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
+//
+// clearotron framework — read a risk framework and its manifest, and say what they declare.
+//
+// The command a customer's counsel runs after writing the pair and before pointing a company at it.
+// It creates nothing, rates nothing and calls nobody: it opens the two files exactly as a run would,
+// reports the ladder in the framework's own order, and where the deck and the manifest disagree it
+// names the band and says what the deck did not do.
+//
+// WHY IT IS ITS OWN COMMAND rather than a flag on the onboarding one. `brandowner add --dry-run`
+// answers "would this create the company I meant", and it does check the framework loads — but a person
+// writing a rubric has no company to create yet, and telling them to phrase their question as a
+// half-finished onboarding is how a check goes unrun. The onboarding command prints this same report,
+// from this same module, so the two can never disagree about what a valid framework is.
+
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+import { invocationPrefix } from "../shared/invocation.mjs";
+import { preflightFramework, formatPreflight } from "../driver/framework-preflight.mjs";
+
+const USAGE = (cmd) => `
+  ${cmd} framework <skills/prelim-search/your-framework.md>
+
+    Reads a risk framework deck and the manifest beside it, and reports what they declare —
+    the ladder, the company the deck names, the shape, and which file answered where.
+    Creates nothing. Rates nothing. Contacts nobody.
+
+    The path is the one a profile carries: it starts with skills/ and is resolved the way a
+    run resolves it, so this reads the file a matter would actually be rated under.
+
+  Exit codes: 0 the deck and the manifest agree · 1 not ready, with the reason · 2 usage
+`;
+
+export function preflightMain(argv, { out = console.log, err = console.error } = {}) {
+  const cmd = invocationPrefix();
+  const args = argv.filter((a) => a !== "--");
+  if (args.includes("--help") || args.includes("-h")) { out(USAGE(cmd)); return 0; }
+  if (args.length !== 1 || args[0].startsWith("-")) { err(USAGE(cmd)); return 2; }
+
+  const report = preflightFramework(args[0]);
+  out(formatPreflight(report));
+  // A substitution is not a refusal — the pair may be perfectly valid — but it is the finding this
+  // command exists to surface, so it is never the difference between exit 0 and exit 1 and is never
+  // silent either. The line is printed above by the formatter.
+  return report.ok ? 0 : 1;
+}
+
+if (isEntrypoint(import.meta.url)) process.exit(preflightMain(process.argv.slice(2)));

package/bin/grant.mjs

@@ -1,37 +1,49 @@
 #!/usr/bin/env node
 // 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
-// grant.mjs — put someone on the guest list, take them off, or see who is on it ( item 2).
+// grant.mjs — give someone access, take it away, or see who has it ( item 2).
 //
 // ── WHY THIS EXISTS ────────────────────────────────────────────────────────────────────────────────
 //
-// The guest list was a JSON file edited by hand. `bin/start.mjs` writes an empty one at install and
-// nothing added a person to it, so for anyone self-hosting the only way to let a second person in was a
-// text editor — and a mistake in that file does not error. `accountsForEmail` simply matches nothing,
-// and the person signs in to an empty world with nothing in any log to say why.
+// The guest list was a JSON file edited by hand. `bin/start.mjs` writes one at install and nothing
+// added a second person to it, so for anyone self-hosting the only way to let a colleague in was a text
+// editor — and a mistake in that file does not error. `resolvePerson` simply matches nothing, and the
+// person signs in to an empty world with nothing in any log to say why.
 //
 // `npm start` and `npm run setup` exist so that installing is not that. Enrolment is the very next thing
 // the same reader does, and it dropped straight back to the editor.
 //
 // ── ONE OPINION ABOUT VALIDITY, NOT TWO ───────────────────────────────────────────────────────────
 //
-// The product already knew what a mistake looked like: `accessView` (driver/portal-config-view.mjs)
-// computes BOTH typo directions for the People & access screen — a grant naming an account its own
-// tenant does not hold, and an account named in a grant that no customer bundle matches. It computed
-// them AFTER the mistake shipped.
+// The change itself is made by `withPerson` (shared/grants-edit.mjs), the editor the portal's People
+// page writes through, so the two writers cannot produce two shapes of one fact — and a company the
+// organisation does not hold is refused there, by the same sentence the page would get.
 //
-// So this command does not grow a second opinion. It builds the grants object it is about to write,
-// runs `accessView` OVER THAT PROPOSED STATE, and refuses if the change would introduce either finding.
-// The screen's report and this refusal are the same code by construction — they cannot drift, and there
-// is no second definition of "a good grant" to keep in step.
+// The product also knew the other typo direction: `accessView` (driver/portal-config-view.mjs) reports a
+// company that no customer bundle matches. It reported it AFTER the mistake shipped. So this command runs
+// `accessView` OVER THE PROPOSED STATE, seen from the top of the tree, and refuses if the change would
+// introduce that finding. The screen's report and this refusal are the same code by construction.
 //
 // The email rule is borrowed the same way: `makePrincipal` refuses a multi-`@` identity outright, so a
 // grant for one could never resolve. Rather than restate the rule, this asks `makePrincipal`.
 //
+// ── A PERSON IS ACCESS PLUS TWO PERMISSIONS ───────────────────────────────────────────────────────
+//
+// Access is where on the tree a person may look: a whole organisation (`--accounts '*'`) or companies
+// it holds. What they may DO is two switches under `people`: `--run` (start and stop clearances) and
+// `--manage` (add people and companies, change settings). Neither flag is the view-only person, and the
+// output says so in a sentence — someone who can read a company's reports and start nothing is a real
+// posture, not a mistake, but it must never be the surprise.
+//
+// Access to everything is not granted here. The person who installs holds it (`clearotron start`
+// writes that entry), and it is CARRIED through every change this command makes to their entry, never
+// dropped: `withPerson` replaces the entry it writes, and a person who held everything and was then
+// given Run here would otherwise lose the whole install with nothing said.
+//
 // ── THE FILE STAYS AUTHORITATIVE ──────────────────────────────────────────────────────────────────
 //
 // This is an editor for that file and never a second store. It stays hand-editable, and anything this
-// command writes a human can read and change back. No browser write path is added here or anywhere.
+// command writes a human can read and change back.
 //
 // WRITTEN ATOMICALLY, because the portal reads this file PER REQUEST — that is what makes a grant land
 // without a restart, and it is also what makes a non-atomic write dangerous: a reader catching a
@@ -52,6 +64,7 @@
 import "../shared/env-local.mjs";
 import { readFileSync, existsSync } from "node:fs";
 import { assertGrantsShape } from "../shared/scope.mjs";   // — one shape check, not a second opinion
+import { withPerson, withOrganisation, withCompany } from "../shared/grants-edit.mjs";   // — the People page's own editors
 import { basename } from "node:path";
 import { atomicWrite } from "../driver/progress.mjs";
 import { accessView } from "../driver/portal-config-view.mjs";
@@ -74,7 +87,7 @@ const out = (msg) => console.log(msg);
 /** The grants file, or a stated refusal. NEVER an invented empty one — a typo in the path would then
  *  silently create a second guest list nobody reads. */
 function readGrants() {
-  if (!existsSync(FILE)) die(`No guest list at ${FILE}. \`clearotron start\` writes an empty one the first time it runs — start the product once, or set CLEAROTRON_ACCESS_FILE if your roster lives elsewhere.`);
+  if (!existsSync(FILE)) die(`No guest list at ${FILE}. \`clearotron start\` writes one the first time it runs — start the product once, or set CLEAROTRON_ACCESS_FILE if your roster lives elsewhere.`);
   let g;
   try { g = JSON.parse(readFileSync(FILE, "utf8")); }
   catch (e) { die(`${basename(FILE)} is not valid JSON (${e.message}). Refusing to touch it — fix it by hand, or the portal will 500 on every request until you do.`); }
@@ -90,49 +103,66 @@ function readGrants() {
 }
 
 /**
- * Every account key a customer bundle actually holds, or NULL when that cannot be established.
+ * Every company a customer bundle actually holds, as `{ key: name }`, or NULL when that cannot be
+ * established.
  *
- * EMPTY IS NULL HERE, DELIBERATELY. `accessView` guards its unknown-account check with
- * `if (known.size && …)` — so an empty set means the check DOES NOT RUN and reports nothing, which is
- * indistinguishable from running and finding nothing. Collapsing empty into null makes the command say
- * "not checked" instead of implying "checked and clean": not probed is not passed.
+ * EMPTY IS NULL HERE, DELIBERATELY. `accessView` guards its unknown-company check with `known.size` — so
+ * an empty map means the check DOES NOT RUN and reports nothing, which is indistinguishable from running
+ * and finding nothing. Collapsing empty into null makes the command say "not checked" instead of implying
+ * "checked and clean": not probed is not passed.
  */
-async function knownAccounts() {
+async function knownCompanies() {
   try {
     const { loadProfiles } = await import("../driver/profiles.mjs");
-    const keys = [...loadProfiles({ force: true }).keys()];
-    return keys.length ? keys : null;
+    const named = [...loadProfiles({ force: true }).entries()]
+      .map(([key, p]) => [key, typeof p?.name === "string" && p.name.trim() ? p.name.trim() : key]);
+    return named.length ? Object.fromEntries(named) : null;
   } catch { return null; }
 }
 
 /**
  * Would this proposed state be a good one? Asked of `accessView`, so the answer is the screen's answer.
  *
+ * SEEN FROM THE TOP OF THE TREE. The screen hides what its viewer cannot see; this command is run by
+ * whoever administers the box, and a finding hidden from it would be a check that did not run.
+ *
  * Returns the findings ATTRIBUTABLE TO THIS CHANGE only. A guest list that already contains someone
  * else's dangling grant is not this operator's problem to fix before they can add a colleague, and
  * refusing on it would make the command unusable on exactly the messy file it exists to tidy.
  */
-function faultsIntroduced(before, after, known, email) {
-  const view = (g) => accessView({ grants: g, knownAccounts: known ?? [], grantsFile: null });
+function faultsIntroduced(before, after, companies, email) {
+  const view = (g) => accessView({ grants: g, viewer: { everything: true }, companies: companies ?? {} });
   const b = view(before), a = view(after);
-  const rowFor = (v) => v.people.filter((p) => p.email === email);
-  const dangling = rowFor(a).flatMap((p) => p.dangling);
+  const dangling = a.people.filter((p) => p.email === email).flatMap((p) => p.dangling);
   const newUnknown = a.unknownAccounts.filter((x) => !b.unknownAccounts.includes(x));
   return { dangling: [...new Set(dangling)], unknownAccounts: newUnknown };
 }
 
+/** What a person may do, in a sentence — the view-only case said as plainly as the others. */
+function mayLine(email, entry) {
+  const run = entry?.run === true, manage = entry?.manage === true;
+  const whole = entry?.everything === true ? ", with access to everything on this install" : "";
+  if (!run && !manage)
+    return `${email} can view what this gives them and do nothing else: no clearance can be started, and nobody added${whole}. Add --run, --manage or both to change that.`;
+  return `${email} may ${[run && "run clearances", manage && "manage (add people and companies, change settings)"].filter(Boolean).join(" and ")}${whole}.`;
+}
+
 function usage(code = 1) {
   // — HELP ASKED FOR GOES TO STDOUT; usage printed as a REFUSAL goes to stderr.
   // This wrote to stderr either way, and it was the only verb of nine that did: `clearotron grant
   // --help | less` showed nothing, and neither did any redirect a reader would try. The exit code
   // already carries the distinction, so it decides the stream.
   const out = code === 0 ? console.log : console.error;
-  out(`clearotron grant — edit the guest list the portal reads
+  out(`clearotron grant — edit who may use this install
 
   grant list
-  grant add <email> --tenant <name> --accounts <key,key|*>
-  grant remove <email> [--tenant <name>]
-  grant remove-tenant <name>
+  grant add <email> --tenant <organisation> --accounts <key,key|*> [--run] [--manage]
+  grant remove <email> [--tenant <organisation>]
+  grant remove-tenant <organisation>
+
+--accounts * is the whole organisation, including companies filed under it later. --run lets the
+person start and stop clearances; --manage lets them add people and companies and change settings.
+With neither they can view what they have access to and nothing else.
 
 The file (${FILE || "CLEAROTRON_ACCESS_FILE unset"}) stays authoritative and hand-editable; this is an
 editor for it. The portal re-reads it per request, so a change lands with no restart.`);
@@ -145,18 +175,21 @@ const flag = (name) => { const i = argv.indexOf(`--${name}`); return i >= 0 ? ar
 
 if (!cmd || cmd === "--help" || cmd === "-h") usage(0);
 
-const grants = readGrants();
-const tenants = grants.tenants;
+let grants = readGrants();
 
 if (cmd === "list") {
-  const known = await knownAccounts();
-  const v = accessView({ grants, knownAccounts: known ?? [], grantsFile: null });
-  if (!v.people.length) out("The guest list is empty. Staff arrive by domain and are not listed here.");
+  const companies = await knownCompanies();
+  const v = accessView({ grants, viewer: { everything: true }, companies: companies ?? {} });
+  if (!v.people.length) out("Nobody has access yet. `clearotron start` gives the person who installs access to everything; `grant add` gives anyone else theirs.");
   for (const p of v.people) {
-    const reach = p.wildcard ? `* (every account ${p.tenant} holds: ${p.accounts.join(", ") || "none"})` : p.accounts.join(", ") || "nothing";
-    out(`${p.email}\n    tenant   ${p.tenant}\n    reaches  ${reach}${p.dangling.length ? `\n    ⚠ DANGLING ${p.dangling.join(", ")} — ${p.tenant} does not hold ${p.dangling.length > 1 ? "these" : "this"}, so it resolves to nothing` : ""}`);
+    const reach = p.access.map((pt) => pt.kind === "everything" ? "everything on this install"
+      : pt.kind === "organisation"
+        ? `the whole of ${pt.name}${pt.name !== pt.key ? ` (${pt.key})` : ""} — every company it holds: ${(grants.tenants[pt.key]?.accounts ?? []).filter((a) => a !== "generic").join(", ") || "none yet"}`
+        : `${pt.key}, in ${pt.org}`).join("; ") || "nothing";
+    const may = [p.permissions.run && "run clearances", p.permissions.manage && "manage"].filter(Boolean).join(" and ") || "view only";
+    out(`${p.email}\n    access   ${reach}\n    may      ${may}${p.dangling.length ? `\n    ⚠ DANGLING ${p.dangling.join(", ")} — the organisation that grants ${p.dangling.length > 1 ? "these does not hold them" : "this does not hold it"}, so it resolves to nothing` : ""}`);
   }
-  if (known === null) out("\nNote: customer bundles could not be read, so accounts were NOT checked against them.");
+  if (companies === null) out("\nNote: customer bundles could not be read, so companies were NOT checked against them.");
   else if (v.unknownAccounts.length) out(`\n⚠ Named in grants but matching no customer bundle: ${v.unknownAccounts.join(", ")}`);
   process.exit(0);
 }
@@ -165,72 +198,88 @@ if (cmd === "add") {
   const email = String(argv[1] ?? "").trim().toLowerCase();
   const tenant = flag("tenant");
   const accountsArg = flag("accounts");
+  const run = argv.includes("--run");
+  const manage = argv.includes("--manage");
   if (!email || !tenant || !accountsArg) usage();
 
-  // THE EMAIL RULE IS makePrincipal's, asked rather than restated. A multi-@ identity is refused there
-  // outright, so a grant for one could never resolve — writing it would be writing a line that cannot
-  // ever match, which is the silent-uselessness this command exists to prevent.
-  if (!makePrincipal({ email, grants: { tenants: {} }, staffDomains: [] }) && email.indexOf("@") !== email.lastIndexOf("@"))
-    die(`"${email}" carries more than one @. The portal refuses those identities outright, so this grant could never match anyone.`);
-  if (!email.includes("@")) die(`"${email}" is not an email address.`);
+  // THE EMAIL RULE IS makePrincipal's, asked rather than restated. Asked over a file in which this address
+  // would see everything, so the only way it resolves to nobody is that the resolver refused the address
+  // itself — which it does, outright, for a multi-@ identity. Writing that grant would be writing a line
+  // that cannot ever match, which is the silent-uselessness this command exists to prevent.
+  if (!makePrincipal({ email, grants: { tenants: {}, people: { [email]: { everything: true } } } })) {
+    if (email.indexOf("@") !== email.lastIndexOf("@"))
+      die(`"${email}" carries more than one @. The portal refuses those identities outright, so this grant could never match anyone.`);
+    die(`"${email}" is not an email address.`);
+  }
+  const list = accountsArg === "*" ? "*" : accountsArg.split(",").map((s) => s.trim()).filter(Boolean);
+  if (list !== "*" && !list.length) die("--accounts named nothing. Use a comma-separated list of account keys, or * for the whole organisation.");
 
   // ── A REFUSAL THAT NAMES THE ROUTE ( — F38) ─────────────────────────────
   //
   // This used to end at "it does not create one", and NOTHING IN THE CLI CREATES ONE: `brandowner`
-  // never writes a tenant, this command refuses to, and `connect` sends the reader here. On a fresh
-  // install the file is {"tenants":{}}, so the documented first run was connect → "run grant" → grant →
+  // never writes a tenant, this command refused to, and `connect` sends the reader here. On a fresh
+  // install the file named no tenant, so the documented first run was connect → "run grant" → grant →
   // "a tenant must already exist" → nothing. A dead end reached by following instructions.
   //
-  // The route exists — it is the file — and `grant --help` documents it. What was missing is that the
-  // refusal which STOPS you did not carry it, so the shape of the object is printed here, against this
-  // install's own path, rather than left to a reader to find in another command's help.
-  // — found in review. THE FIRST TENANT IS CREATED HERE. Before this, enrolling anyone
-  // on a fresh install ran out of road: the file is {"tenants":{}}, `brandowner` does not write tenants,
-  // and this command refused because none existed. 2176's F38 fix printed the JSON shape into the
-  // refusal, which is better than a bare stop and still asks a person to hand-edit the file the product
-  // is meant to manage.
+  // THE FIRST TENANT IS CREATED HERE — ONLY WHEN THE ROSTER HOLDS NONE, and that limit is the point.
+  // Creating on any unknown name would mean a typo mints an organisation nobody meant, silently, in the
+  // file the door reads — so once there is a roster to typo against, the refusal stays and lists what
+  // exists.
   //
-  // ONLY WHEN THE ROSTER IS EMPTY, and that limit is the point. Creating on any unknown name would mean
-  // a typo mints a tenant nobody meant, silently, in the file the door reads — so once there is a roster
-  // to typo against, the refusal stays and lists what exists.
-  const firstTenant = !tenants[tenant] && Object.keys(tenants).length === 0;
-  if (firstTenant) {
-    // `--accounts` is already required by the usage check above, so there is no second guard for it
-    // here: a branch that cannot be reached reads as protection and provides none.
-    //
-    // SEEDED FROM --accounts, not created empty. Created empty, the very next check — "tenant does not
-    // hold <key>" — refuses, nothing is written, and the first tenant can never be granted anything:
-    // the dead end moves one line down rather than closing. Found by driving the enrolment rather than
-    // reading the diff. For a tenant that does not exist yet, the accounts this grant names ARE the
-    // accounts the tenant covers; a narrower set for the user comes from editing it afterwards.
-    tenants[tenant] = {
-      accounts: accountsArg === "*" ? "*" : accountsArg.split(",").map((x) => x.trim()).filter(Boolean),
-      users: {},
-    };
-    out(`Creating the first tenant "${tenant}" in ${FILE}, holding: ${accountsArg}`);
+  // THROUGH THE SHARED EDITORS. `withOrganisation` derives the key from the name, so the key is taken
+  // from what it returns rather than assumed equal to what was typed. SEEDED FROM --accounts, not
+  // created empty: for an organisation that does not exist yet, the companies this grant names ARE the
+  // companies it holds. `*` names none, so the organisation starts holding no company and the person gets
+  // the whole of it — a legitimate state, and the only one: an organisation's list is never "*".
+  let key = tenant;
+  if (!grants.tenants[tenant] && Object.keys(grants.tenants).length === 0) {
+    try {
+      const made = withOrganisation(grants, { name: tenant });
+      key = made.key;
+      grants = made.grants;
+      for (const account of list === "*" ? [] : list) grants = withCompany(grants, { tenant: key, account });
+    } catch (e) { die(`Refusing: ${e.message}. Nothing written.`); }
+    out(`Creating the first tenant "${key}" in ${FILE}, holding: ${list === "*" ? "no company yet — * gives the person the whole organisation, including companies filed under it later" : list.join(", ")}`);
   }
-  if (!tenants[tenant]) die(`No tenant "${tenant}". It must already exist with its accounts — this command grants access to a tenant, and it creates one only when there are none at all, so that a typo cannot mint a tenant nobody meant.
-Tenants: ${Object.keys(tenants).join(", ")}
+  if (!grants.tenants[key]) die(`No tenant "${tenant}". It must already exist with its companies — this command grants access to a tenant, and it creates one only when there are none at all, so that a typo cannot mint a tenant nobody meant.
+Tenants: ${Object.keys(grants.tenants).join(", ")}
 
 To add another, put it in ${FILE} — the shape is:
-    { "tenants": { "${tenant}": { "accounts": ["<brand-owner-key>"], "users": {} } } }
-"accounts" holds the brand-owner keys this tenant may act for; \`clearotron doctor\` names the ones this install has, under "brand owner(s) resolve here". Then run this command again.`);
+    { "tenants": { "${tenant}": { "name": "<its name>", "accounts": ["<company-key>"], "users": {} } } }
+"accounts" holds the company keys this tenant holds, and a company belongs to one tenant only; \`clearotron doctor\` names the ones this install has, under "brand owner(s) resolve here". Then run this command again.`);
 
-  const before = JSON.parse(JSON.stringify(grants));
-  const value = accountsArg === "*" ? "*" : accountsArg.split(",").map((s) => s.trim()).filter(Boolean);
-  if (value !== "*" && !value.length) die("--accounts named nothing. Use a comma-separated list of account keys, or * for every account the tenant holds.");
-  tenants[tenant].users = { ...(tenants[tenant].users ?? {}), [email]: value };
+  const before = structuredClone(grants);
+  const held = (Array.isArray(grants.tenants[key].accounts) ? grants.tenants[key].accounts : []).join(", ") || "(none)";
+  const points = list === "*" ? [{ tenant: key }] : list.map((account) => ({ tenant: key, account }));
+  const peopleKey = Object.keys(grants.people ?? {}).find((k) => k.toLowerCase() === email);
+  const had = peopleKey === undefined ? null : grants.people[peopleKey];
+  // THE SWITCHES ARE WRITTEN ONLY WHEN ONE IS ASKED FOR. A person with no entry is already view-only, so
+  // writing `{ run: false, manage: false }` for them adds a line that says nothing; and a person who
+  // already holds Run must not lose it because a company was added without repeating the flag.
+  const setSwitches = run || manage;
+  let after;
+  try {
+    after = withPerson(grants, { email, points, switches: { run, manage, everything: had?.everything === true }, setSwitches });
+  } catch (e) {
+    if (/does not hold/.test(e.message))
+      die(`Refusing: ${e.message}.\nThat grant would resolve to nothing and fail as a silent 404 for ${email}.\nAccounts "${key}" holds: ${held}. Nothing written.`);
+    die(`Refusing: ${e.message}. Nothing written.`);
+  }
 
-  const known = await knownAccounts();
-  const faults = faultsIntroduced(before, grants, known, email);
+  const companies = await knownCompanies();
+  const faults = faultsIntroduced(before, after, companies, email);
   if (faults.dangling.length)
-    die(`Refusing: tenant "${tenant}" does not hold ${faults.dangling.join(", ")}.\nThat grant would resolve to nothing and fail as a silent 404 for ${email}.\nAccounts "${tenant}" holds: ${(tenants[tenant].accounts ?? []).join(", ") || "(none)"}`);
+    die(`Refusing: tenant "${key}" does not hold ${faults.dangling.join(", ")}.\nThat grant would resolve to nothing and fail as a silent 404 for ${email}.\nAccounts "${key}" holds: ${held}`);
   if (faults.unknownAccounts.length)
     die(`Refusing: ${faults.unknownAccounts.join(", ")} ${faults.unknownAccounts.length > 1 ? "match" : "matches"} no customer bundle.\nThe grant would be written and reach nothing. Check the account key, or add the bundle first.`);
-  if (known === null) console.error("Note: customer bundles could not be read, so the account keys were NOT checked against them.");
+  if (companies === null) console.error("Note: customer bundles could not be read, so the account keys were NOT checked against them.");
 
-  atomicWrite(FILE, JSON.stringify(grants, null, 2) + "\n");
-  out(`${email} → ${tenant} (${value === "*" ? "every account the tenant holds" : value.join(", ")})\nWritten to ${basename(FILE)}. The portal re-reads per request — no restart.`);
+  atomicWrite(FILE, JSON.stringify(after, null, 2) + "\n");
+  out(`${email} → ${key} (${list === "*" ? "the whole organisation" : list.join(", ")})`);
+  if (setSwitches) out(mayLine(email, after.people?.[email]));
+  else if (had) out(`${mayLine(email, had)} Their permissions are unchanged; pass --run and --manage to set them.`);
+  else out(mayLine(email, null));
+  out(`Written to ${basename(FILE)}. The portal re-reads per request — no restart.`);
   process.exit(0);
 }
 
@@ -239,7 +288,7 @@ if (cmd === "remove") {
   const only = flag("tenant");
   if (!email) usage();
   let removed = 0;
-  for (const [name, t] of Object.entries(tenants)) {
+  for (const [name, t] of Object.entries(grants.tenants)) {
     if (only && name !== only) continue;
     if (t?.users && email in t.users) { delete t.users[email]; removed++; }
     // AN EMPTY `users` MAP IS NOT A DELETED TENANT, and this writes the former deliberately: the tenant
@@ -247,18 +296,27 @@ if (cmd === "remove") {
     // tenant here would destroy configuration the operator never asked to remove, and it round-trips —
     // `remove-tenant` is the other verb, and it is explicit.
   }
-  if (!removed) die(`${email} is not on the guest list${only ? ` for "${only}"` : ""}. Nothing written.`);
+  // AND THE PERSON'S OWN ENTRY, when they are removed from everywhere. Their permissions and their access
+  // to everything live under `people`, not in any tenant, so a removal that left that entry would leave a
+  // person who sees everything still seeing everything. Removed from one tenant, they may still hold
+  // access elsewhere, and their entry stays.
+  const peopleKey = only ? undefined : Object.keys(grants.people ?? {}).find((k) => k.toLowerCase() === email);
+  if (peopleKey !== undefined) delete grants.people[peopleKey];
+  if (!removed && peopleKey === undefined) die(`${email} is not on the guest list${only ? ` for "${only}"` : ""}. Nothing written.`);
   atomicWrite(FILE, JSON.stringify(grants, null, 2) + "\n");
-  out(`Removed ${email} from ${removed} tenant(s). Written to ${basename(FILE)}.`);
+  out(`Removed ${email} from ${removed} tenant(s)${peopleKey !== undefined ? ", and their permissions under people" : ""}. Written to ${basename(FILE)}.`);
+  const kept = Object.entries(grants.people ?? {}).find(([k]) => k.toLowerCase() === email)?.[1];
+  if (kept?.everything === true)
+    out(`${email} still has access to everything through their entry under people. \`grant remove ${email}\` without --tenant takes that away too.`);
   process.exit(0);
 }
 
 if (cmd === "remove-tenant") {
   const name = String(argv[1] ?? "").trim();
   if (!name) usage();
-  if (!tenants[name]) die(`No tenant "${name}". Nothing written.`);
-  const people = Object.keys(tenants[name].users ?? {}).length;
-  delete tenants[name];
+  if (!grants.tenants[name]) die(`No tenant "${name}". Nothing written.`);
+  const people = Object.keys(grants.tenants[name].users ?? {}).length;
+  delete grants.tenants[name];
   atomicWrite(FILE, JSON.stringify(grants, null, 2) + "\n");
   out(`Removed tenant "${name}"${people ? ` and the ${people} grant(s) it held` : ""}. Written to ${basename(FILE)}.`);
   process.exit(0);