clearotron 0.2.4 → 0.3.0-beta.1

package/.env.example

@@ -356,7 +356,7 @@ SIGNA_FIXTURES_DIR=             # canned signa payloads — the $0 seam for that
 # sets one. This name has no default — unset, the lane refuses. Moving it there would spend that
 # header's credibility, which every other row in that file depends on, to buy a tidier taxonomy.
 # `.env.example` promises "what you decide at install", and a must-set variable fits deciding-at-install
-# better than it fits never-set-one. Owner ruling, 2026-08-30.
+# better than it fits never-set-one. Ruling, 2026-08-30.
 #
 # GIVING THE LANE A DEFAULT WAS CONSIDERED AND REFUSED: refuse-by-name-when-unset is the honest design —
 # the same family as the pool root, where an unset value THROWS rather than quietly resolving somewhere
@@ -525,7 +525,7 @@ CLEAROTRON_WHATSAPP_OPERATOR_COPY=
 CLEAROTRON_TEST_FIXTURE_PROFILES=
 
 # `1` makes the profile loader return the BUNDLED demo account (demo-brand-owner, marked `demoData`).
-# A fresh install resolves `generic` alone — owner ruling 2026-09-08, so nobody has to clean demo
+# A fresh install resolves `generic` alone — ruling 2026-09-08, so nobody has to clean demo
 # material out of an environment they just made — and the demo brings its own account when it runs.
 # Set by `clearotron demo`, by `clearotron start --demo`, and by scripts/test-run.mjs.
 #
@@ -535,3 +535,14 @@ CLEAROTRON_TEST_FIXTURE_PROFILES=
 # Read by driver/profiles.mjs.
 # effect: harness
 CLEAROTRON_DEMO_PROFILES=
+
+# ── The organisation setup names ──────────────────────────────────────────────────────────────────
+#
+# Your organisation's name. `npm run setup` asks for it directly after the sign-in address and writes it
+# here, quoted, so a name holding a `#` survives. The first `clearotron start` files it as the first
+# organisation in the grants file (CLEAROTRON_ACCESS_FILE) when that file holds none; from then on the
+# grants file holds the name, renaming is an edit there, and this is not read. Unset or empty, no
+# organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a
+# demo never reads it. Read by bin/start.mjs.
+# effect: deployment
+CLEAROTRON_ORGANISATION_NAME=

package/CONTRIBUTING.md

@@ -80,7 +80,7 @@ product and will not be published. Its absence weakens nothing you can run — t
 the machinery, and the scenario suite covers the answers. The validation ladder, from the $0 offline
 suite to a paid live run, is [docs/E2E.md](docs/E2E.md).
 
-**Some comments cite issues you cannot open** — `(tracker issue 324)` and the like, against the private tracker this
+**Some comments cite issues you cannot open** — `` and the like, against the private tracker this
 repository was cut from. They are being removed rather than preserved.
 [ADR-0005](docs/decisions/0005-comments-carry-reasoning.md) is the ruling and states what a new comment
 has to meet; read it there rather than from a summary here. New work cites this repository's issues

package/INSTALL.md

@@ -168,7 +168,7 @@ you want the second one** — the first assumes access to the repository, which
 
 **This is the development tree, and it is for contributors.** If you want to run a clearance, take one
 of the two routes above instead. A clone is not a smaller version of the package — it carries the
-fixtures and sample brand owners the project develops against, and those load as real records. They
+fixtures and sample companies the project develops against, and those load as real records. They
 are not yours and they are not in the package, which excludes them deliberately.
 
 ```
@@ -381,7 +381,7 @@ CLARIVATE_API_KEY=...                    # the credential for the provider named
 # EUIPO_CLIENT_ID=... / EUIPO_CLIENT_SECRET=...
 EUIPO_ENVIRONMENT=production              # REQUIRED with euipo — sandbox | production are SEPARATE
                                           # deployments over different corpora. There is no default:
-                                          # unset, the adapter refuses by name (tracker issue 1149 item 2).
+                                          # unset, the adapter refuses by name.
 
 # ── Web research — REQUIRED for all four products (see §1) ─────────────
 PERPLEXITY_API_KEY=...
@@ -445,33 +445,36 @@ staleness thresholds that decide when an index is too old to trust are in
 
 ### The four things, and what contains what
 
-Read this before the rest of the section. The product uses three words for overlapping ideas, and
-nothing until now said how they nest — the owner of this product reached for a fourth word, "org",
-which names nothing here at all. That confusion is real and it belongs to the documentation, not to
-the reader.
+Read this before the rest of the section. Everything is one tree, and a person is given access to
+points on it.
 
-| What it is | The word the product uses | Where it lives | What creates it |
+| What it is | What the product calls it | Where it lives | What creates it |
 |---|---|---|---|
-| The deployment's own boundary — one installation's whole world | **tenant** | a key in `grants.json` | nothing yet; you write the key by hand |
-| A brand owner you do clearances for | **account**, and the CLI calls it **brand owner** | a bundle in the customer store, keyed by an account key | `npx clearotron brandowner add <key>` |
-| One engagement under that brand owner — its classes, jurisdictions, platforms | **project** | inside that account's bundle | `npx clearotron project add` |
-| A person who may see some of it | **user** | `grants.json`, under the tenant | `npx clearotron grant add`, then `npx clearotron key issue` |
-
-Nesting, in one line: **a tenant contains accounts; an account contains projects; a user is enrolled in
-a tenant and reaches a named subset of that tenant's accounts.**
-
-Two consequences worth stating, because both surprised the person who commissioned the product:
-
-- **An account does not span tenants.** `grants.json` maps each tenant to its own account keys, so the
-  same brand owner reached from two tenants is two grants, not one shared object.
+| A group of people and the companies they clear for — a firm, a brand team, one customer of a hosted install | **organisation** (`tenant` in `grants.json`) | a key under `tenants` in `grants.json`, with its `name` | setup creates the first; after that, a key you add to `grants.json` |
+| A company you do clearances for | **company** (`account` in `grants.json` and on the wire; the CLI calls it **brand owner**) | a bundle in the customer store, keyed by an account key, and listed under exactly one organisation | the portal's `+ New company`, or `npx clearotron brandowner add <key>` |
+| One engagement under that company — its classes, jurisdictions, platforms | **project** | inside that company's bundle | `npx clearotron project add` |
+| Someone who may see some of it | **person** | `grants.json`: their access under each organisation's `users`, their two switches under `people` | the portal's People page, or `npx clearotron grant add` |
+
+Nesting, in one line: **an organisation contains companies; a company contains projects; a person is
+given access to points on that tree — the whole install, an organisation, or one company — and sees
+everything below them.**
+
+Three consequences worth stating, because each has surprised someone:
+
+- **A company belongs to exactly one organisation.** The guest list is refused at load if a company is
+  listed under two; another organisation's people are given access to it where it lives.
+- **A person holds two switches, and nothing else is a permission.** **Run clearances** starts and
+  stops them; **Manage** adds people, adds companies and changes settings. Viewing is not a permission:
+  access is viewing. A person with no entry under `people` sees what their access covers and starts
+  nothing.
 - **A key grants no reach of its own.** `npx clearotron key issue` mints the identity a person's assistant
-  presents; what that identity may see is decided by their `grant`. Enrol first, issue second — a key
-  without a grant reaches nothing, and is not an error anywhere.
+  presents; what that identity may see and do is decided by the guest list at the moment of each call.
+  Enrol first, issue second — a key for someone with no access reaches nothing, and is not an error
+  anywhere.
 
-**⚠ The words are not yet aligned across the surfaces.** `grants.json` says *tenant*, the CLI verb is
-*brandowner*, and the portal and `grant`'s own output say *account*. This table states the containment
-so a reader can act today; choosing ONE customer-facing word and moving the file, the CLI and the UI
-onto it is a product decision that has not been taken.
+**The file keeps its words.** The screens say organisation, company and person; `grants.json`, the wire
+and the command line keep `tenant` and `account`, and the CLI verb stays `brandowner`. Moving them would
+break every file and script written against them.
 
 
 A clearance run is shaped by a **customer profile** — a small JSON file that declares that customer's
@@ -741,10 +744,12 @@ You sign in as `<your-username>@localhost` unless you say otherwise:
 npx clearotron start --user you@example.com
 ```
 
-The address is written to `.env`, so it is asked for once. It is also the staff identity for this
-install: in this mode the portal admits exactly one address, so it sees everything, and enrolling
-clients is the grants file (`CLEAROTRON_ACCESS_FILE`, §8) exactly as on a
-hosted instance.
+The address is written to `.env`, so it is asked for once. It is also the first person on this
+install: the first start writes it into the grants file (`CLEAROTRON_ACCESS_FILE`, §8) with access to
+everything and both permissions, Run clearances and Manage. Setup asks for your organisation's name
+directly after the address, and the same start files it there as your first organisation. The address
+admits nobody else at its domain; enrolling anyone else is that same file, exactly as on a hosted
+instance.
 
 **No authentication is switched off to make this work, and none can be.** Both doors prove who the
 caller is — the portal by passphrase and a signed session cookie, the engine door by a mandatory
@@ -888,13 +893,13 @@ set:
 
 ### The client connector's ingress is not integrator-supplied
 
-The client connector is the door a brand owner's assistant talks to, and it
+The client connector is the door a company's assistant talks to, and it
 is **part of the product** rather than something a deployment invents. A reader who reaches the
 Use-your-AI page and finds Connect buttons that do nothing has been failed by the install, not by
 their own integration work.
 
-**Two shapes, and the line between them is what your assistant can do — not where it runs.** Owner
-ruling 2026-09-03, on the vendor's own documented behaviour:
+**Two shapes, and the line between them is what your assistant can do — not where it runs.** Ruling
+2026-09-03, on the vendor's own documented behaviour:
 
 1. **An assistant that can launch a local process** — Claude Code, Claude Desktop's local config,
    Codex CLI, an agent that runs commands. It spawns the server over stdio. No address, no key, no
@@ -1005,11 +1010,23 @@ infer it from an install step. The operational side — issuing and rotating gra
 What belongs here is only what you set at install time.
 
 **The guest list.** `CLEAROTRON_ACCESS_FILE` turns account scoping on for **every face at once** — the
-portal, the MCP read face, and the client connector. `npx clearotron start` (§6) writes an empty
-roster (`{"tenants": {}}`) into its state directory, which is your own staff access and no clients yet.
+portal, the MCP read face, and the client connector. `npx clearotron start` (§6) writes one into its
+state directory the first time it runs: you, with access to everything, your organisation if setup was
+told its name, and nobody else yet.
 [examples/grants.example.json](examples/grants.example.json) is a runnable guest list over the demo
 clients.
 
+**Giving someone access.** `npx clearotron grant add` writes the same file the portal's People page
+writes:
+
+```
+npx clearotron grant add <email> --tenant <organisation> --accounts <key,key|*> [--run] [--manage]
+```
+
+`--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 see what their access covers and start nothing.
+
 **Keys for people.** `npx clearotron grant` enrols someone; it decides what they may see and issues
 nothing. The key their assistant actually presents comes from a different verb:
 
@@ -1032,10 +1049,17 @@ Said plainly rather than dressed as a verb, because the distinction costs real t
 key issue` mints ACCOUNT keys only**, and `npx clearotron grant` mints nothing at all. This page
 previously sent readers to `grant` for an ops token, which is why the sentence is now this long.
 
-**When you have to re-mint one.** The portal's own trigger lane runs on a pinned ops token, and its
-account list is frozen at the moment it was minted. Add a brand owner afterwards and clearances for that
-account are refused — `your grant [...] does not include account "..."` — until the token is re-minted
-with the new list and the environment updated. Nothing re-mints it for you.
+**When you have to re-mint one.** Not on the ordinary path any more, and this paragraph used to say
+otherwise. The portal takes its ops credential afresh at the start of each call, capped to the company
+roster as it stands, so a company created after the portal started can run a clearance and stop one
+without anybody re-minting anything.
+
+The pinned credential minted at startup is still the fallback, and it is where this matters. If the
+signing secret cannot be read or the company store cannot be listed, the portal uses that one rather than
+widening the cap to get the call through — so its account list is frozen at the moment it was minted, and
+a company created since is refused at the door with `your grant [...] does not include account "..."`.
+The portal says so in its log when it happens. That is when you re-mint by hand, with the new list, and
+update the environment.
 
 ### Putting a surface behind your identity provider
 

package/bin/brandowner.mjs

@@ -12,7 +12,7 @@
 //
 // ── THE FRAMEWORK IS SET HERE, AND THAT NEEDED A NEW DOOR ─────────────────────────────────────────
 //
-// Owner ruling, 2026-08-29: the risk framework stays MANDATORY at onboarding, with a DEFAULT BACKUP so
+// Ruling, 2026-08-29: the risk framework stays MANDATORY at onboarding, with a DEFAULT BACKUP so
 // onboarding is never blocked. This sets `frameworkPath` ALWAYS — the client's own when supplied, the
 // Generic default otherwise — and says out loud which one it used.
 //
@@ -59,180 +59,22 @@ import { assertProfileKey, profileStoreResolution, CONTEXT_PACK_FILE, validatePr
 import { DEFAULT_FRAMEWORK, loadFrameworkManifest } from "../driver/framework.mjs";
 import { defaultWriteProfile } from "../driver/profile-service.mjs";
 import { config } from "../driver/driver.config.mjs";
+import { preflightFramework, formatPreflight } from "../driver/framework-preflight.mjs";
 import { makeCommittableAudit, commitWithAuditRow, makeStoreCommit, resolveStoreRepoRoot } from "../shared/store-in-repo.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 // Shared with `project add`, which asks an identical question of the same variable — see the
 // module header for why this is not two copies.
 import { Refusal, storeForAdd } from "../shared/onboarding-store.mjs";
 
-// ── the framework, which is the point of the setup ─────────────────────────────────────────────────
-/**
- * Resolve the framework this brand owner will be rated under, as the ruling words it: the client's own
- * when supplied, the Generic default otherwise, and always stated.
- *
- * ABSENT AND BROKEN ARE NOT THE SAME EVENT and the ruling separates them deliberately. Absent means the
- * client has not given us their framework yet — onboarding proceeds under the Generic default, named.
- * Broken means someone TRIED to select one and it does not resolve, and falling back there would rate a
- * client's matters under a framework nobody chose while the output said everything was fine.
- *
- * The profile validator checks the SHAPE of this string only (`skills/prelim-search/<file>.md`, no
- * escape) and never whether the file is there — so a shape-valid path to a document that does not exist
- * validates cleanly and fails at rating time, which is the wrong place to find out.
- */
-export function resolveFramework(requested, {
-  resolveSkill = (rel) => config.resolveSkillPath(rel),
-  loadManifest = loadFrameworkManifest,
-} = {}) {
-  if (requested == null || String(requested).trim() === "")
-    return { path: DEFAULT_FRAMEWORK, source: "default" };
-
-  const path = String(requested).trim();
-  // Shape first, and by the profile validator's own rule rather than a second copy of it: a path that
-  // would be refused at load must be refused here, in the same words, before anything is written.
-  if (!/^skills\/prelim-search\/[^/]+\.md$/.test(path) || path.includes(".."))
-    throw new Refusal(
-      `--framework must name a document of the form "skills/prelim-search/<file>.md" (got ${JSON.stringify(path)}). `
-      + `A profile selects a SHIPPED framework, never an arbitrary path.`);
-
-  // RESOLVED THE WAY THE RATING STAGE RESOLVES IT, never by joining the repo root. `skills/...` paths
-  // are relative to the DRIVER's skills directory, and a deployment may serve them from a doctrine
-  // overlay (CLEAROTRON_INSTRUCTIONS_DIR) instead. Joining the repo root would have looked in a
-  // directory that does not exist, refused every valid framework on every install, and — worse in the
-  // other direction — been blind to the overlay a deployment actually reads.
-  const deck = resolveSkill(path);
-  if (!existsSync(deck))
-    throw new Refusal(
-      `--framework names ${path}, and there is no such document on this install (resolved to ${deck}). `
-      + `Refusing rather than rating this brand owner's matters under the Generic default: a framework `
-      + `somebody chose and that does not resolve is a mistake, not an absence.`);
-
-  // The manifest is DERIVED from the deck path, never a separate knob — and it is what the validators,
-  // the renderer and the profile page read to know the framework's band vocabulary. A deck whose
-  // manifest will not load produces a customer whose page cannot state their own ladder.
-  //
-  // ASKED, NOT RE-CHECKED. An `existsSync` on the manifest here would be a second opinion about the
-  // same fact: `loadFrameworkManifest` already refuses a missing sidecar by name
-  // (`framework_manifest_missing:<path>`) and is the exact read the rating stage makes. Two checks
-  // means two messages to keep in step, and the one this file could write would be the one that goes
-  // stale.
-  let manifest;
-  try {
-    manifest = loadManifest(resolveSkill, path);
-  } catch (e) {
-    throw new Refusal(
-      `--framework names ${path}, and the framework will not load: ${String(e?.message ?? e)}. `
-      + `Refusing rather than falling back: a framework somebody chose and that does not resolve is a `
-      + `mistake, not an absence.`);
-  }
-  return { path, source: "supplied", manifest };
-}
-
-// ── the profile this writes ────────────────────────────────────────────────────────────────────────
-/**
- * Which marketplaces this brand owner's searches cover — supplied, or the Generic default, SAID OUT LOUD.
- *
- * A customer bundle is a COMPLETE document in this design, not an overlay on generic: every shipped
- * profile carries its own `platforms`, and the loader requires a non-empty array on every file. The
- * command had no way to supply one and set none, so every bundle it wrote failed to load on this field
- * as well as on the `key` field above — two independent invalidities, and onboarding could not produce
- * a loadable brand owner at all.
- *
- * Defaulting rather than refusing, and naming it, is this command's own established idiom: the same
- * ruling governs the framework one function down. Which marketplaces a client's clearance searches is
- * not a detail to decide silently, so an operator who supplies nothing is TOLD what they got and can
- * refine it in the portal.
- */
-export function resolvePlatforms(supplied, roster) {
-  if (supplied?.length) return { platforms: supplied, source: "supplied" };
-  const house = roster?.get?.("generic")?.platforms ?? [];
-  if (!house.length)
-    throw new Refusal(
-      "no --platforms was given and the Generic default carries none, so there is nothing to onboard this "
-      + "brand owner with. Pass --platforms, or repair the generic profile in the store.");
-  return { platforms: [...house], source: "house default" };
-}
+// ── what a valid company bundle is ─────────────────────────────────────────────────────────────────
+// MOVED TO driver/company-bundle.mjs when the browser became the second door. Re-exported here because
+// this file was the only home they ever had and callers import them from it; the definition is now in
+// one place and both doors ask it, rather than two doors agreeing by inspection.
+import {
+  resolveFramework, resolvePlatforms, buildProfile, rosterAsItStands, assertRosterAccepts,
+} from "../driver/company-bundle.mjs";
 
-export function buildProfile({ key, name, domains, platforms, framework, industry }) {
-  // NO `key` IN THE DOCUMENT. The loader derives it from the FILENAME and injects it — readProfilesLayer
-  // composes `{ key, ...p }` — so a `key` written here is redundant on the way in and fatal on the way
-  // out: it is not in KNOWN_PROFILE_KEYS, and the deny-unknown-key gate hard-fails the whole roster over
-  // it. Every bundle this command wrote carried one, so the first successful onboarding made the store
-  // unloadable and the next command to read profiles threw. The parameter stays — the filename and the
-  // roster checks are addressed by key — it simply does not travel into the file.
-  const profile = { name, platforms };
-  if (domains?.length) profile.matchDomains = domains;
-  if (industry) profile.industry = industry;
-  // ALWAYS SET, per the ruling. `frameworkFor` would fall back to the same value if this were absent —
-  // but "the tool sets it" is the point of the setup, and an explicit selection is what makes the
-  // receipt below mean anything.
-  profile.frameworkPath = framework.path;
-  return profile;
-}
-
-// ── the proposed roster, validated whole ───────────────────────────────────────────────────────────
-/**
- * Validate the candidate the way the deployment will read it: as one member of the roster, not alone.
- *
- * `loadProfiles` composes every profile in the store and throws on the FIRST cross-profile conflict it
- * finds — a domain claimed twice, most of all. That throw is not scoped to the offending file: it stops
- * the roster loading at all. So the only honest check is over the proposed state, which is what
- * bin/grant.mjs does with `accessView` for exactly the same reason.
- */
-/**
- * The roster as it stands, where AN EMPTY STORE IS AN EMPTY ROSTER — F42.
- *
- * `loadProfiles` with an explicit `dir` reads that directory ALONE and refuses a store with no
- * `generic.json`, which is right for what that refusal is for: `generic` is the universal fallback every
- * unprofiled job resolves to, and a RUN against a store without it would silently reprofile a client.
- * The explicit-dir form deliberately has no fall-through, because the fixtures that build a roster
- * assert on precisely that roster and layering the bundled set underneath would widen three set-level
- * guards until none still tested its own name.
- *
- * BUT THIS COMMAND IS NOT RUNNING A CLEARANCE. It reads the store to answer one question — does this key
- * or one of its domains already exist — and on a fresh install the honest answer is "no, there is
- * nothing here yet". Instead it stack-traced on the FIRST day-one command a new operator types, with a
- * refusal about a file they had never heard of and did not need: the runtime resolves `generic` from the
- * product's bundled set through the OVERLAY path, so a deployment store never needs its own copy.
- *
- * So the missing-generic refusal is caught BY NAME and answered as the empty roster it describes. Caught
- * by name rather than broadly, because every other thing that loader throws — an overlapping domain, an
- * unknown key, an unreadable store — is a real refusal this command must still relay.
- */
-export function rosterAsItStands(store, loadProfiles) {
-  try { return loadProfiles({ dir: store, force: true }); }
-  catch (e) {
-    if (/generic\.json is REQUIRED/.test(String(e?.message ?? ""))) return new Map();
-    throw e;
-  }
-}
-
-export function assertRosterAccepts({ store, key, profile, loadProfiles }) {
-  // THE LOADER'S OWN VALIDATOR, over the CANDIDATE — the discipline `project add` already applies to an
-  // overlay, in the same words, for the same reason: whatever the tree would refuse at load is refused
-  // here, before anything is written. Everything below this line reads the store AS IT STANDS, which is
-  // why none of it could ever see a bad field in the file about to be added: the candidate never met the
-  // loader until the next command did, and by then the write had landed.
-  const v = validateProfileEdit(key, profile);
-  if (!v.ok)
-    throw new Refusal(`the brand owner bundle is not valid, so nothing was written:\n  ${v.errors.join("\n  ")}`);
-
-  const existing = rosterAsItStands(store, loadProfiles);
-  if (existing.has(key))
-    throw new Refusal(
-      `a brand owner "${key}" already exists in ${store}. This command creates; it does not overwrite an `
-      + `existing bundle. Edit it in the portal, or remove the file deliberately first.`);
-
-  for (const d of profile.matchDomains ?? []) {
-    const dl = String(d).toLowerCase();
-    for (const [otherKey, other] of existing) {
-      if ((other.matchDomains ?? []).some((o) => String(o).toLowerCase() === dl))
-        throw new Refusal(
-          `domain "${dl}" is already claimed by the brand owner "${otherKey}". Two owners claiming one `
-          + `domain makes the WHOLE roster refuse to load on the next start — not just this bundle — so `
-          + `nothing has been written.`);
-    }
-  }
-}
+export { resolveFramework, resolvePlatforms, buildProfile, rosterAsItStands, assertRosterAccepts };
 
 
 // ── argument parsing ───────────────────────────────────────────────────────────────────────────────
@@ -338,6 +180,13 @@ export async function add(argv, {
     if (contextPack) out(`would create ${join(store, CONTEXT_PACK_FILE(args.key))}`);
     out(frameworkLine);
     out(platformsLine);
+    // THE SAME REPORT `clearotron framework` PRINTS, from the same module. A dry run already proved the
+    // framework LOADS; that is a smaller question than the one the operator has, because a deck whose
+    // manifest parses can still name bands the deck never defines, and the profile screen answers that by
+    // quietly omitting the box. Two checks of one property drift; this is one check with two doors.
+    out("");
+    out(formatPreflight(preflightFramework(framework.path)));
+    out("");
     out(`nothing was written (--dry-run)`);
     return { written: false, store, profile, framework };
   }
@@ -407,7 +256,7 @@ export async function add(argv, {
       if (gap.uncovered.length) {
         out("");
         out(`  ⚠ NOT YET STARTABLE — ${triggerCapWarning(gap)}`);
-        out(`    The portal will offer a clearance for ${args.key} and the engine door will refuse it until the trigger token is re-minted.`);
+        out(`    The portal will still start a clearance for ${args.key}: it re-takes its credential on each call. This matters when it cannot — then it uses the token above and the door refuses.`);
       }
     }
   } catch (e) {

package/bin/clearotron.mjs

@@ -58,6 +58,7 @@ export const VERBS = {
   grant:   ["bin/grant.mjs"],
   key:     ["bin/key.mjs"],
   brandowner: ["bin/brandowner.mjs"],
+  framework: ["bin/framework-preflight.mjs"],
   project: ["bin/project.mjs"],
   passphrase: ["bin/passphrase.mjs"],
   sync:    ["bin/uspto-sync.mjs"],
@@ -79,6 +80,7 @@ export const SUMMARY = {
   grant:   "enrol a client, or list who may see what",
   key:     "issue the key a person's own assistant presents — after you have enrolled them with `grant`",
   brandowner: "onboard a brand owner — create its bundle and set the risk framework its matters are rated under",
+  framework: "check a risk framework deck and its manifest before a matter is rated under it. Writes nothing",
   project: "add an engagement under a brand owner — the classes, jurisdictions and platforms it searches",
   passphrase: "report or RESET the portal's local sign-in — the recovery for a lost passphrase",
   sync:    "build or update the free US register index (a large download, and hours of ingest)",
@@ -202,7 +204,7 @@ const [verb, ...rest] = process.argv.slice(2);
     process.exit(code ?? 0);
   });
 
-  // ── A SIGNAL MUST REACH THE CHILD, BECAUSE THIS IS THE ONLY PID A READER CAN SEE (tracker issue 176) ─
+  // ── A SIGNAL MUST REACH THE CHILD, BECAUSE THIS IS THE ONLY PID A READER CAN SEE ─────────────────────
   //
   // The header above says this file "spawns and forwards, and does not look at what it is forwarding".
   // That was written about ARGUMENTS and read as though it covered signals, which it did not.

package/bin/connect.mjs

@@ -48,13 +48,13 @@ import { createServer } from "node:net";
 import { CONNECT_CLIENTS, clientById, whatItNeeds } from "../shared/connect-clients.mjs";
 import { stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";
 import { defaultDenylistPath, clientDoorAddress, clientDoorPort, clientDoorState, enablePlan, applyEnablePlan, describeChange, recordConnectKey, CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
-import { mintToken, tokenId, accountsForEmail, loadGrants } from "../shared/scope.mjs";
+import { mintToken, tokenId, resolvePerson, loadGrants } from "../shared/scope.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
 import { atomicWrite } from "../driver/progress.mjs";
 // — F40. SERVER_INSTALL_SET is what `bin/start.mjs` re-exports as
 // BACKGROUND_UNITS; taken from shared/ so this verb does not reach into another bin/ entry point.
 import { SERVER_INSTALL_SET, unitHealthVerdict } from "../shared/server-units.mjs";
-import { checkoutMove, movePosture, describeMove, describeConflict } from "../shared/checkout-move.mjs";   // tracker issue 193
+import { checkoutMove, movePosture, describeMove, describeConflict } from "../shared/checkout-move.mjs";
 import { unitEnvironment, unitValue, couldNotDetermine } from "../driver/unit-environment.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { looksLikeBusFailure, systemdSaid, userBusEnv, CAPTURE_STDERR,
@@ -62,13 +62,13 @@ import { looksLikeBusFailure, systemdSaid, userBusEnv, CAPTURE_STDERR,
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 // `userBusEnv` and `busRemedy` MOVED TO shared/systemd-failure.mjs, unchanged, because
-// `start --background` needs the same answers and had none (tracker issue 203). Their reasoning went
+// `start --background` needs the same answers and had none. Their reasoning went
 // with them; this file imports them and passes `userBusEnv()` at every `systemctl` call it makes,
 // `showUnit` included — which is the property that makes deriving the bus safe here and is why `start`
 // does not do it at two of its five.
 
 /**
- * What a half-finished connect has ALREADY written by the time `step` failed — tracker issue 121.
+ * What a half-finished connect has ALREADY written by the time `step` failed.
  *
  * The reader's problem is not only that a step failed; it is not knowing whether to run `connect` again,
  * run `disconnect` first, or leave it alone. A message that names a command and stops leaves a
@@ -95,7 +95,7 @@ function alreadyApplied(step) {
 /**
  * A systemd failure, said in the reader's terms — the REASON first, then the remedy that fits it.
  *
- * TWO DEFECTS, ONE SITE (tracker issue 121). The calls ran with `stdio: "ignore"`, so systemd's own
+ * TWO DEFECTS, ONE SITE. The calls ran with `stdio: "ignore"`, so systemd's own
  * explanation was thrown away before anyone could read it and the whole output was `connect: Command
  * failed: systemctl --user daemon-reload`. And the bus remedy was appended to EVERY failure, so a unit
  * that would not start — a bound port, a bad ExecStart — told the reader to export XDG_RUNTIME_DIR: a
@@ -108,7 +108,7 @@ function alreadyApplied(step) {
 /**
  * Does this failure say the SESSION BUS is missing, rather than anything about the unit?
  *
- * ONE AUTHORITY, because two readers now ask it (tracker issue 130, criterion 3). The failure text
+ * ONE AUTHORITY, because two readers now ask it (criterion 3). The failure text
  * below offers the bus remedy on a yes, and the health reader refuses to translate a yes into "the door
  * is not open" — that mistranslation is the defect, and a second copy of this test is how the two would
  * come to disagree about which failures are bus failures.
@@ -172,7 +172,7 @@ function runningEnv() {
 }
 
 /**
- * Which tree each installed unit's LIVE process is executing (tracker issue 193).
+ * Which tree each installed unit's LIVE process is executing.
  *
  * NOT the units' env file, which is the file this verb is about to write — after the write the two
  * agree and the drift is invisible. The running processes are the only witnesses, and they are
@@ -282,11 +282,11 @@ function portOwnerOf(port, bound) {
 /**
  * Read properties off a user unit — the ONE place this file asks systemd anything read-only.
  *
- * ── WHY IT EXISTS (tracker issue 130, criterion 3) ───────────────────────────────────────────────────
+ * ── WHY IT EXISTS (criterion 3) ──────────────────────────────────────────────────────────────────────
  *
  * Two readers here called `systemctl --user show` directly and neither did what the WRITERS in this
- * same file already do: neither passed `userBusEnv()`, so both failed in exactly the shell tracker issue
- * 121 was filed about, and neither captured stderr, so systemd's own "Failed to connect to bus" went
+ * same file already do: neither passed `userBusEnv()`, so both failed in exactly the shell the
+ * refusal report was filed about, and neither captured stderr, so systemd's own "Failed to connect to bus" went
  * straight past the reader with no remedy beside it.
  *
  * The writers were fixed and these were missed, which made the product WORSE on this path rather than
@@ -370,7 +370,7 @@ export function unitIsHealthy(name, { show = showUnit, pause = settle } = {}) {
   pause(3000);
   const { fields: f, error } = show(name, ["ActiveState", "SubState", "NRestarts"]);
   if (error) {
-    // ── A BUS THAT COULD NOT BE REACHED IS NOT A DOOR THAT IS DOWN (tracker issue 130) ────────────
+    // ── A BUS THAT COULD NOT BE REACHED IS NOT A DOOR THAT IS DOWN ────────────────────────────────
     //
     // Returning false here is what made the operator worse off than before that fix.
     // The caller renders false as "the door is not open, so no key was issued" — a confident, wrong,
@@ -396,11 +396,20 @@ function enableTheDoor({ have, identity, client = null, dryRun, portFree, portOw
   const reach = { publicAddress: have.publicAddress, reachabilityKnown: envKnown };
   // Resolved HERE because it reads a file, and handed to the pure planner as a fact. A door this verb
   // opens for an identity that is granted nothing is a credential with no reach.
+  //
+  // ENROLLED MEANS A PERSON WITH ACCESS SOMEWHERE, asked of the resolver the door itself reads. The
+  // flat company list could not say it: a person whose only reach is their organisation's Generic holds
+  // no company, and read as enrolled in nothing. No grants file answers "*", as it always has.
   let granted;
-  try { granted = accountsForEmail(identity, loadGrants()); } catch { granted = undefined; }
+  try {
+    const grants = loadGrants();
+    const person = grants ? resolvePerson(identity, grants) : null;
+    granted = !grants ? "*" : !person ? [] : person.accounts === "*" ? "*"
+      : [...person.accounts, ...(person.genericOrgs.length ? ["generic"] : [])];
+  } catch { granted = undefined; }
   // The env file the UNIT reads, not this shell — found by the drive: a shell-exported secret passed
   // every plan check while the door died at birth reading an env file that lacked it.
-  // ── THE PLAN CHECKED THE FILE AND THE MINT READ THE SHELL (tracker issue 130) ─────────────────────
+  // ── THE PLAN CHECKED THE FILE AND THE MINT READ THE SHELL ─────────────────────────────────────────
   //
   // `unitEnvHasSecret` below asks the UNIT'S ENV FILE, which is the right question for the DOOR: a
   // process reads its environment at start, so a secret that is only in this shell is one the door
@@ -425,7 +434,7 @@ function enableTheDoor({ have, identity, client = null, dryRun, portFree, portOw
     portOwner: (p) => (p === have.port ? (portOwner ?? (portFree ? "free" : "stranger")) : "stranger") });
   if (!plan.possible) return { ok: false, blockers: plan.blockers, fix: plan.fix };
 
-  // ── A MACHINE-WIDE SETTING IS NOT THIS VERB'S TO MOVE IN SILENCE (tracker issue 193) ───────────────
+  // ── A MACHINE-WIDE SETTING IS NOT THIS VERB'S TO MOVE IN SILENCE ───────────────────────────────────
   //
   // `plan.settings` carries CLEAROTRON_CHECKOUT_DIR set to THIS checkout, and `setEnvValue` replaces
   // rather than preserves — so running this from a worktree repoints every unit's ExecStart and the
@@ -500,7 +509,7 @@ function enableTheDoor({ have, identity, client = null, dryRun, portFree, portOw
     recordNote = "This key's id could not be read, so it was NOT recorded — `clearotron disconnect` cannot revoke it; it dies only at its own expiry.";
   } else {
     try {
-      // ── THE TRUE CAUSE, NOT WHATEVER THREW (tracker issue 130) ─────────────────────────────────
+      // ── THE TRUE CAUSE, NOT WHATEVER THREW ─────────────────────────────────────────────────────
       //
       // With no grants file configured this reached `atomicWrite(undefined, …)` and the reader got a
       // raw Node type error inside a client-facing sentence — a live key, outside `disconnect`'s
@@ -561,7 +570,7 @@ async function render(offer, have, { dryRun, running, allowMove = false }) {
     return 0;
   }
 
-  // ── AN ADDRESS ROUTE ALWAYS MINTS NOW (owner ruling 2026-09-03,) ─────────────
+  // ── AN ADDRESS ROUTE ALWAYS MINTS NOW (ruling 2026-09-03,) ─────────────
   //
   // This used to be `if (offer.enables)` — mint only when the row said the door still had to be turned
   // on. Under settled point 2 the door auto-starts, so no row asks for that any more and every offer
@@ -586,7 +595,7 @@ async function render(offer, have, { dryRun, running, allowMove = false }) {
     const bound = await portIsFree(have.port);
     const r = enableTheDoor({ have, identity, client: offer.client.id, dryRun, env: running.env,
       envKnown: running.known, portFree: bound, portOwner: portOwnerOf(have.port, bound), allowMove });
-    // SAID BEFORE THE OUTCOME, whichever way it goes (tracker issue 193): a reader who is about to be
+    // SAID BEFORE THE OUTCOME, whichever way it goes: a reader who is about to be
     // told the door is open needs to have already read that the deployment moved trees to open it.
     for (const line of r.moveSays ?? []) say(line);
     if (!r.ok) {
@@ -708,12 +717,12 @@ async function main() {
   return await render(whatItNeeds(chosen, have), have, { dryRun, running, allowMove: argv.includes("--allow-checkout-move") });
 }
 
-// THE DISPATCH RUNS ONLY WHEN THIS FILE IS THE COMMAND (tracker issue 121). Without the guard, importing
+// THE DISPATCH RUNS ONLY WHEN THIS FILE IS THE COMMAND. Without the guard, importing
 // this module to drive one of its message helpers RUNS THE WHOLE VERB — the arm for the half-applied
 // failure path opened an interactive prompt and hung the suite. `bin/clearotron.mjs` carries the same
 // guard for the same reason, written up there: "importing it to read the verb table would DISPATCH".
 //
-// Ten other files under bin/ still lack it. That is a class, filed as tracker issue 183 rather than
+// Ten other files under bin/ still lack it. That is a class, filed separately rather than
 // swept in here — each one needs verifying that it still runs as a command.
 if (isEntrypoint(import.meta.url)) {
   main().then((code) => process.exit(code ?? 0), (e) => { console.error(`connect: ${e.message}`); process.exit(2); });