clearotron 0.3.0-beta.7 → 0.3.0-beta.9

package/README.md

@@ -19,33 +19,41 @@ no gateway, no platform, and nothing about your matters reaches us.
 
 ## Install
 
-**See it work first, with nothing checked out.**
+**See it work first, with nothing installed.**
 
 ```bash
 npx clearotron demo
 ```
 
-That fetches the published package — it will ask once before downloading — then replays a finished
-clearance into a local pool and opens the report in your browser. No account, no credentials, no network
-calls to us.
+That fetches the published package — it will ask once before downloading — then replays finished
+clearances into a local portal and prints the portal's address and the passphrase to sign in with. Open
+the address in your browser. No account, no credentials, no network calls to us.
 
 **Then install it.**
 
 ```bash
-npm install -g clearotron
+npx clearotron install
 ```
 
-Node 22.13 or newer, on macOS or Linux. That puts `clearotron` on your `PATH`; every command below
-works in that short form. **On Windows the demo above runs natively; a real clearance needs WSL2.**
-Native Windows clearances are planned for a later release. Until then the engine does not run on native
-Windows: it resolves the reasoning CLI the POSIX way, and a clearance started there refuses at preflight.
+Node 22.13 or newer, on macOS or Linux. It needs no root: it puts the program under `~/.local`, with the
+`clearotron` command in `~/.local/bin`, then asks one question at a time and checks each credential
+before it saves it. With `~/.local/bin` on your `PATH`, every command below works in the short form;
+otherwise use the full path `install` prints at the end. **On Windows the demo above runs natively; a
+real clearance needs WSL2.** Native Windows clearances are planned for a later release. Until then the
+engine does not run on native Windows: it resolves the reasoning CLI the POSIX way, and a clearance
+started there refuses at preflight.
+
+`npm install -g clearotron` also works where npm's global directory is yours to write. On a Linux Node
+from the distribution or NodeSource that directory is `/usr`, owned by root, and npm refuses with
+`EACCES`. Do not answer that with `sudo`; install under your home instead:
+`npm install -g clearotron --prefix ~/.local`.
 
-That command gives you the **stable** release — the one that has run a real clearance end to end before it
-was published. If you want the newest code instead, a beta is published whenever there is something worth
-testing — deliberately, days apart, not on every merge:
+`npx clearotron install` gives you the **stable** release — the one that has run a real clearance end to
+end before it was published. If you want the newest code instead, a beta is published whenever there is
+something worth testing — deliberately, days apart, not on every merge:
 
 ```bash
-npm install -g clearotron@beta
+npx clearotron@beta install
 ```
 
 What each channel promises, and when a stable is cut: [docs/RELEASES.md](docs/RELEASES.md). If you are not
@@ -53,17 +61,17 @@ sure, the first command is the one you want.
 
 ## Quick start
 
-Check the install before it does anything. `doctor` only reads — it writes nothing, calls nobody, and
-names whatever is still missing:
+With it installed, check what it found before it does anything. `doctor` only reads — it writes nothing,
+calls nobody, and names whatever is still missing:
 
 ```bash
-npx clearotron doctor
+clearotron doctor
 ```
 
-Then start the product and open the portal it prints:
+Then start the product and open the portal address it prints:
 
 ```bash
-npx clearotron start
+clearotron start
 ```
 
 That is the portal a brand owner uses. Ordering a clearance is the same screen — describe it in a
@@ -82,11 +90,10 @@ rights-holders behind them by jurisdiction:
 
 ![The conflict landscape, with rights-holders grouped by jurisdiction](docs/assets/portal-conflict-landscape.jpg)
 
-Then run your own. `install` asks one question at a time and checks each credential before it saves it:
+Then run your own: order it in the portal, or hand the engine a job file:
 
 ```bash
-npx clearotron install
-npx clearotron run --job my-job.json
+clearotron run --job my-job.json
 ```
 
 ## How it fits together

package/bin/example.mjs

@@ -47,6 +47,7 @@ import { spawn } from "node:child_process";
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
 import { envFrom } from "../shared/env-aliases.mjs";   // — resolves EITHER spelling; names the retired one because that is the live-writable half
 import { isFrozen, demoChildren, publishSource } from "../driver/demo-container.mjs";   // — one definition of what a frozen demo is, for the player AND the gate
+import { ensureDemoProgram, demoProgramEnv } from "../shared/permanent-install.mjs";
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -369,8 +370,19 @@ console.log(`  Removing this demo later is one directory:  ${removeDirectory(dem
 strayFromAnOlderDemo();
 console.log("");
 
-const child = spawn(process.execPath, [join(REPO, "bin", "start.mjs"), ...startArgs], {
-  cwd: REPO, stdio: ["ignore", "inherit", "inherit"],
+// ── RUN FROM NPX, THE SERVICES RUN FROM THE DEMO'S OWN COPY ─────────────────────────────────────────
+//
+// Started from npm's cache, the supervisor printed every command it gives the reader as `cd <npm's cache>
+// && npx clearotron …`: the passphrase reset, the key, the free-port hint, `start --background`. Each one
+// failed once npm cleaned that cache (measured on a published beta, 2026-09-11). So the copy the demo
+// keeps in `<base>/program` is laid down first and the supervisor is started from it, which also puts the
+// portal and the doors on a program that outlives the cache. Everywhere else, and when the copy cannot be
+// made, it starts from here as before.
+const programRoot = ensureDemoProgram({ base: demoBase, say: (line) => console.log(line) });
+const startFrom = programRoot ?? REPO;
+const child = spawn(process.execPath, [join(startFrom, "bin", "start.mjs"), ...startArgs], {
+  cwd: startFrom, stdio: ["ignore", "inherit", "inherit"],
+  env: programRoot ? demoProgramEnv(process.env) : process.env,
 });
 child.on("error", (e) => die(`demo: could not start the portal: ${String(e?.message ?? e)}`));
 // Its exit code is the demo's. A supervisor that swallowed a child's refusal would report a demo that

package/bin/key.mjs

@@ -29,7 +29,9 @@
 import "../shared/env-local.mjs";   // side effect: apply the install's .env — FIRST, before anything reads process.env
 import { invocationPrefix } from "../shared/invocation.mjs";
 import { existsSync, readFileSync } from "node:fs";
-import { defaultGrantsPath } from "./start.mjs";
+import { defaultGrantsPath, installPaths } from "./start.mjs";
+import { demoTokenSecretPath } from "../shared/client-door.mjs";
+import { resolvePerson } from "../shared/scope.mjs";   // the door's own reading of the guest list, so one answer serves both
 import { mintFromOptions } from "../mcp-server/mint-token.mjs";
 
 const argv = process.argv.slice(2);
@@ -44,6 +46,7 @@ const USAGE = `usage: ${p}clearotron key issue <email> [options]
 
     --accounts a,b     cap the key to these account keys as well (omit = whatever their grant allows)
     --ttl-days <n>     how long it is valid (default 90)
+    --base <dir>       the install or demo to issue for, when it is not the one set up in ~/trademark
 
 The token is printed ONCE on stdout and stored nowhere — possession is the credential. Everything
 else goes to stderr, including the jti that revokes it.`;
@@ -65,6 +68,17 @@ const email = positional[0];
 if (!email) die(`who is the key for? Give the person's email.\n\n${USAGE}`);
 if (!email.includes("@")) die(`"${email}" is not an email address — the subject of an account key is the identity their assistant presents, and the grants file is keyed on it.`);
 
+// `--base` NAMES THE INSTALL, as it does for `start` and `passphrase`: its guest list, and — for a demo,
+// which keeps its signing secret in its own base rather than in any settings file — that secret. Without
+// it the verb read the install's settings and refused to issue a key for a running demo.
+const baseAt = rest.indexOf("--base");
+const base = baseAt >= 0 ? rest[baseAt + 1] : null;
+if (baseAt >= 0 && (!base || base.startsWith("--"))) die(`--base needs a directory.\n\n${USAGE}`);
+if (base) {
+  const secretFile = demoTokenSecretPath(base);
+  if (existsSync(secretFile)) process.env.TRADEMARK_MCP_TOKEN_SECRET = readFileSync(secretFile, "utf8").trim();
+}
+
 const ttlDays = Number(flag("--ttl-days") ?? 90);
 const accounts = flag("--accounts") ? flag("--accounts").split(",").map((s) => s.trim()).filter(Boolean) : null;
 
@@ -93,15 +107,19 @@ for (const line of minted.notes) console.error(line);
 // inert. STDERR, so the token stays alone on stdout and `key issue ... > token.txt` keeps working —
 // that split is deliberate and this must not undo it.
 try {
-  const rosterPath = defaultGrantsPath();
+  const rosterPath = base ? installPaths(base).grants : defaultGrantsPath();
   if (!existsSync(rosterPath)) {
     console.error(`\nNOTE: no guest list at ${rosterPath} yet, so nothing grants ${email} anything and this key will be refused at the door. \`clearotron start\` writes the list; then: clearotron grant add ${email} --tenant <name> --accounts <brand-owner-key>`);
   } else {
+    // THE DOOR'S OWN RESOLVER DECIDES, not a second reading of the file. This walked `tenants[].users`
+    // alone, and the demo's guest list grants its account through the top-level `people` map — so the
+    // demo's own key came with a note saying the door would refuse it, over a key the door accepts
+    // (driven 2026-09-11). One reader for one question.
     const roster = JSON.parse(readFileSync(rosterPath, "utf8"));
-    const tenants = roster?.tenants && typeof roster.tenants === "object" ? roster.tenants : {};
-    const listed = Object.values(tenants).some((t) => t?.users && Object.prototype.hasOwnProperty.call(t.users, email));
+    const person = resolvePerson(email, roster);
+    const listed = Boolean(person && (person.everything || person.accounts?.length || person.organisations?.length));
     if (!listed)
-      console.error(`\nNOTE: ${email} is on no tenant in ${rosterPath}, so this key resolves to no accounts and the door will refuse it. Grant them access with: clearotron grant add ${email} --tenant <name> --accounts <brand-owner-key>`);
+      console.error(`\nNOTE: ${email} is granted nothing in ${rosterPath}, so this key resolves to no accounts and the door will refuse it. Grant them access with: clearotron grant add ${email} --tenant <name> --accounts <brand-owner-key>`);
   }
 } catch (e) {
   // A ROSTER THIS COMMAND CANNOT READ IS NOT A ROSTER SAYING THE SUBJECT IS ABSENT. Said as what it is,

package/bin/onboard.mjs

@@ -63,7 +63,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";   // read the process table here; moved that to shared/process-table.mjs
 import { homedir, userInfo } from "node:os";
-import { invocationPrefix } from "../shared/invocation.mjs";   // — one rule for how the reader invokes us
+import { invocationPrefix, installRoute, reachableCommand } from "../shared/invocation.mjs";   // — one rule for how the reader invokes us
 import { nodeFloorVerdict } from "../shared/node-floor.mjs";   // — the floor is package.json engines, not a constant here
 import { invocationForm } from "../shared/invocation.mjs";   // — and WHY that form
 import { standFrom } from "../shared/invocation.mjs";   // is this tree one npm replaces?
@@ -130,6 +130,12 @@ function readIfPresent(path) {
 }
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
+// A PACKAGED INSTALL IS NOT A CHECKOUT. doctor says which one it is talking to, and names only commands
+// that run there: npm's scripts and a checkout's tree are not where a package's reader stands.
+const PACKAGED = installRoute(REPO) === "packaged";
+const THIS_TREE = PACKAGED ? "the installed package" : "this checkout";
+// The example job, by the path it has in THIS install, so the printed command runs from any directory.
+const EXAMPLE_JOB = join(REPO, "examples", "job.euipo.json");
 const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed: one resolver, so moving this file later is one line
 // WHAT IS READ IS NOT ALWAYS WHERE THE NEXT WRITE GOES. An install configured before the move still
 // has its file at the old path, and the loader still reads it — so every READ here asks
@@ -1105,7 +1111,10 @@ export async function runCheck() {
     say("      Restart whatever supervises them; this command does not, because which supervisor owns");
     say("      them is a property of your deployment and not of this checkout.");
   } else if (running.state === "unknown") {
-    warn(`could not tell whether running programs are on the current tree: ${running.detail}`);
+    // A PACKAGED INSTALL HAS NO TREE TO BE BEHIND. npm replaces the whole package on an update, so this
+    // question belongs to a checkout, and on a package it is a `!` nothing can ever clear.
+    if (PACKAGED) info("running programs against a checkout's tree: not applicable to a packaged install");
+    else warn(`could not tell whether running programs are on the current tree: ${running.detail}`);
   }
 
   // ── AND THE MORE DANGEROUS ANSWER: A DIFFERENT TREE, NOT AN OLDER ONE ──────────────────────────────
@@ -1137,7 +1146,8 @@ export async function runCheck() {
     if (elsewhere.programs.length > 6) say(`      … and ${elsewhere.programs.length - 6} more`);
     say("      Either point the install back at the tree they run from, or restart them onto this one.");
   } else if (elsewhere.state === "unknown") {
-    warn(`could not tell whether running programs are on a different checkout: ${elsewhere.detail}`);
+    if (PACKAGED && !configuredTree) info("running programs on a different checkout: not applicable to a packaged install");
+    else warn(`could not tell whether running programs are on a different checkout: ${elsewhere.detail}`);
   } else if (elsewhere.state === "unplaced") {
     // PRINTED, because the alternative is silence that reads as a clean answer. Nothing here was placed
     // on a tree, which is not the same as everything being on the right one, and the reader is the only
@@ -1343,7 +1353,7 @@ export async function runCheck() {
     const installMode = engineMode(engineInventory(invEnv));
     if (installMode === ENGINE_MODES.DEMO) {
       info("MODE: demo — everything works except starting a NEW search. The example report, its audit trail "
-        + "and the MCP connection are live right now; `npm run example` needs no engine.");
+        + `and the MCP connection are live right now; \`${reachableCommand("demo")}\` needs no engine.`);
       // NAMES THE COMMAND, AND THE RESTART. The settings page says both now, and a doctor that named
       // the program but not how to install it — or that left out the restart, which is what actually
       // unsticks a reader who has just installed it — would be the third opinion this issue exists to
@@ -1493,6 +1503,9 @@ export async function runCheck() {
     } else if (form.form === "shim-path") {
       warn(`${form.dir} is not on this shell's PATH, so the bare \`clearotron\` will not resolve here`);
       info(`add it with: export PATH="${form.dir}:$PATH"  — or open a new login shell`);
+    } else if (form.form === "npx-pinned") {
+      info(`this is running from npm's npx cache, so the commands below name this version through npx (\`${form.prefix.trim()}\`), `
+        + `which works from any directory and after npm cleans its cache; \`${invoke("install")}\` puts \`clearotron\` on your PATH`);
     } else if (form.shimKind === "ours-other-install") {
       warn(`${form.shim} is a shim for a DIFFERENT install (${form.otherInstall})`);
       info(`re-run \`${invoke("install")}\` to point the bare name at this one`);
@@ -1548,9 +1561,9 @@ export async function runCheck() {
   {
     const inCheckout = (p) => isInsideCheckout(p, REPO);
     for (const [name, what] of [
-      ["CLEAROTRON_CUSTOMERS_DIR", "customers resolve to the bundled demo roster IN this checkout"],
-      ["CLEAROTRON_INSTRUCTIONS_DIR", "doctrine resolves to the bundled files IN this checkout"],
-      ["PROFILE_REPO_ROOT", "the portal's profile editor commits INTO this checkout"],
+      ["CLEAROTRON_CUSTOMERS_DIR", `customers resolve to the bundled demo roster IN ${THIS_TREE}`],
+      ["CLEAROTRON_INSTRUCTIONS_DIR", `doctrine resolves to the bundled files IN ${THIS_TREE}`],
+      ["PROFILE_REPO_ROOT", `the portal's profile editor commits INTO ${THIS_TREE}`],
     ]) {
       // — WHICH NAME THE READER IS TOLD IS NOT ONE QUESTION, IT IS TWO.
       //
@@ -1891,7 +1904,8 @@ export async function runCheck() {
       info(`the units are installed but their environment could not be read (${unitEnv?.why ?? "no reason given"}) — `
         + "whether the services read an overlay is not judged here");
     }
-    if (report.ok && report.overlayConfigured) say("\n  Full detail: npm run doctrine-report");
+    if (report.ok && report.overlayConfigured)
+      say(`\n  Full detail: ${PACKAGED ? `node ${join(REPO, "scripts", "doctrine-report.mjs")}` : "npm run doctrine-report"}`);
   } catch (e) {
     // An unreadable overlay THROWS by design (config.resolveSkillPath refuses rather than falling back
     // to the product's copy). Surfaced here rather than allowed to abort the whole check: the doctor's
@@ -2224,15 +2238,26 @@ export async function runCheck() {
   say("\n  Portal sign-in");
   {
     const { authView } = await import("../driver/portal-config-view.mjs");
+    // A BOX WITH NO UNITS RUNS THE PORTAL `clearotron start` LAUNCHES, as the line below says, and start
+    // hands that portal `PORTAL_AUTH_MODE=local` and refuses any other declared mode (bin/start.mjs). So on
+    // such a box the door is start's, not the bare service's fronted default. Reading the bare default told
+    // a fresh home that the portal would refuse to start and that nobody could use it; `start` then came
+    // up on the local sign-in and created the grants file (measured on a published beta, 2026-09-11).
+    const startLaunched = !hosted;
+    const declaredAuth = String(effectiveForService("PORTAL_AUTH_MODE")?.v ?? "").trim();
     const door = authView({
-      mode: effectiveForService("PORTAL_AUTH_MODE")?.v ?? "",
+      mode: startLaunched ? "local" : declaredAuth,
       oidcIssuer: effectiveForService("PORTAL_OIDC_ISSUER")?.v ?? "",
       team: effectiveForService("CF_ACCESS_TEAM")?.v ?? "",
       jwksUrl: effectiveForService("PORTAL_JWKS_URL")?.v ?? "",
       emailClaim: effectiveForService("PORTAL_EMAIL_CLAIM")?.v ?? "",
       authHeader: effectiveForService("PORTAL_AUTH_HEADER")?.v ?? "",
     });
-    const typed = door.declared ? `PORTAL_AUTH_MODE=${door.declared}` : "PORTAL_AUTH_MODE is unset";
+    const typed = declaredAuth ? `PORTAL_AUTH_MODE=${declaredAuth}`
+      : startLaunched ? "PORTAL_AUTH_MODE is unset, and `start` runs the local sign-in" : "PORTAL_AUTH_MODE is unset";
+    if (startLaunched && declaredAuth && declaredAuth.toLowerCase() !== "local")
+      problem(`${typed}: \`${reachableCommand("start")}\` refuses it, because start is the local install `
+        + "and runs the local sign-in; that mode belongs to a hosted deployment's units");
     // NOT A TICK, AND THAT IS THE POINT. This reads the environment THIS command is
     // typed in. `bin/start.mjs` INJECTS `PORTAL_AUTH_MODE: "local"` into the portal's own environment,
     // and a systemd unit's EnvironmentFile can name a third thing — so a green tick here was a
@@ -2297,7 +2322,13 @@ export async function runCheck() {
       const { makePrincipal } = await import("../driver/portal-access.mjs");
       // ASKED OF THE SERVICE'S OWN ENVIRONMENT. Reading this command's file here is what produced a hard
       // ✗ claiming nobody could use a portal that was admitting its operator on every request.
-      const grantsFile = effectiveForService("CLEAROTRON_ACCESS_FILE")?.v ?? "";
+      // ON A BOX `start` RUNS, an unset grants file is the one start creates on its first run, admitting
+      // the person who started it (`paths.grants` in bin/start.mjs). Before that run it does not exist,
+      // which is a first start still to come, not a portal nobody can use.
+      const namedGrants = effectiveForService("CLEAROTRON_ACCESS_FILE")?.v ?? "";
+      const startGrants = startLaunched && !namedGrants ? startPaths({ env: {} }).grants : null;
+      const beforeFirstStart = Boolean(startGrants) && !existsSync(startGrants);
+      const grantsFile = namedGrants || (beforeFirstStart ? "" : startGrants ?? "");
       let grants = null, unreadable = null;
       if (grantsFile) {
         try { grants = JSON.parse(readFileSync(grantsFile, "utf8")); }
@@ -2310,7 +2341,10 @@ export async function runCheck() {
       // A FAILURE TO LOOK IS NOT A LOCKOUT. On a hosted box whose unit environment
       // could not be read, every name above resolves empty — which is indistinguishable from a box that
       // has genuinely configured nothing, and would print the loudest ✗ in this command on no evidence.
-      if (!serviceKnown) {
+      if (beforeFirstStart) {
+        info(`no grants file yet: the first \`${reachableCommand("start")}\` creates ${startGrants} and gives the person `
+          + "who runs it access to everything");
+      } else if (!serviceKnown) {
         info("who may use this portal is not judged here: the units' environment could not be read, so a "
           + "grants file configured there would be invisible to this check");
       } else if (unreadable) {
@@ -3945,11 +3979,13 @@ try {
 
   say(`\n  ${style.bold("Start here:")}\n`);
   say(`    ${invocationPrefix()}clearotron start\n`);
-  say("      Starts the portal and the engine door, prints one address, and opens it. That address is");
-  say("      the product: you order a clearance from it and read the report there.\n");
+  say("      Starts the portal and the engine door and prints one address to open in your browser. That");
+  say("      address is the product: you order a clearance from it and read the report there.\n");
   say(`  ${style.dim(`Also: \`${invocationPrefix()}clearotron demo\` replays a finished report with no keys and no model calls;`)}`);
-  say(`  ${style.dim(`\`${invocationPrefix()}clearotron run --job examples/job.euipo.json\` runs a first real clearance on the EU register.`)}`);
-  say(`  ${style.dim("Each still works the old way too — `npm start`, `npm run example`, `node driver/pipeline.mjs`.")}\n`);
+  say(`  ${style.dim(`\`${invocationPrefix()}clearotron run --job ${/\s/.test(EXAMPLE_JOB) ? `"${EXAMPLE_JOB}"` : EXAMPLE_JOB}\` runs a first real clearance on the EU register.`)}`);
+  // THE OLD WAY IS A CHECKOUT'S. A package has no npm scripts where its reader stands.
+  if (!PACKAGED) say(`  ${style.dim("Each still works the old way too — `npm start`, `npm run example`, `node driver/pipeline.mjs`.")}`);
+  say("");
 
   // WHY THOSE LINES LOOK THE WAY THEY DO, when they are not the bare verb.
   //

package/bin/start.mjs

@@ -111,22 +111,23 @@ async function runTables() {
 import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { storeInRepo, storeOutsideRepoMessage, storeCommitRefusal } from "../shared/store-in-repo.mjs";   //
 import { stdioConnectOffer } from "../shared/stdio-connect.mjs";
-import { demoProgramPlan } from "../shared/permanent-install.mjs";   // — a demo from npx keeps its own copy
+import { ensureDemoProgram } from "../shared/permanent-install.mjs";   // — a demo from npx keeps its own copy
 import { mergeEnvFile } from "../shared/env-file-merge.mjs";
 import { mcpOriginFor } from "../shared/lane-address.mjs";   // — one author for the origin
 import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "../shared/server-units.mjs";   // — one authority, two callers
 // — the door --background now INSTALLS, and the one authority for the settings
 // it refuses to start without. (Until 2026-09-03 this import read "the one unit --background may
 // tolerate and never manage"; settled point 2 superseded that.)
-import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
+import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort, demoTokenSecret, demoTokenSecretPath, keyIssueCommand } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
 import { createServer } from "node:net";
 import { listenErrorMessage, nextFreePort } from "../shared/listen.mjs";
 import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { invocationPrefix, invoke } from "../shared/invocation.mjs";   // — the banner names the verb
-import { unitEnvPath } from "../shared/env-local.mjs";   // — the file the units read, named once
+import { invocationPrefix, invoke, reachableCommand } from "../shared/invocation.mjs";   // — the banner names the verb
+import { unitEnvPath, activeEnvPath } from "../shared/env-local.mjs";   // — the file the units read, named once
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // ONE KEY=value reader, in a leaf: render-units is a COMMAND, and importing it from here closed a cycle
 import { homedir, userInfo } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { usageBlock } from "../shared/usage-block.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -142,6 +143,7 @@ import { addressRefusal } from "../shared/staff-domain.mjs";
 import { withPerson, withOrganisation, withCompany } from "../shared/grants-edit.mjs";
 import { assertGrantsShape, resolvePerson } from "../shared/scope.mjs";
 import { backgroundManager } from "../shared/os-advice.mjs";
+import { recordRunning } from "../shared/running-start.mjs";
 import { frontingVariablesSet } from "../shared/install-auth.mjs";   // — one owner for what counts as a proxy in front of a door
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -909,6 +911,11 @@ if (isMain) {
   // Decided before any path is, because in a demo every path below is the demo's own. The posture
   // itself is described at the DEMO block further down.
   const DEMO = argv.includes("--demo");
+  // A DEMO HAS NO BACKGROUND FORM, and asking for one is refused before anything is written. The
+  // background path installs units that run the reader's own install, so `--demo --background` would set
+  // up an empty install in their home and call it the demo.
+  if (DEMO && wantBackground)
+    fatal("the demo has no background form — it runs as long as its terminal does. `--background` starts your own install as services, not the demo.");
   // The same base `npm run setup` writes under, so whichever of the two a reader ran first, the other
   // finds the same install rather than a second one beside it.
   // Whatever the environment already says wins over the base-derived default, for every path — a reader
@@ -916,6 +923,35 @@ if (isMain) {
   // which `startPaths` says why. One author, because `doctor` asks the same function what the services
   // were handed.
   const paths = startPaths({ env: process.env, base: flag("--base", join(homedir(), DEMO ? "trademark-demo" : "trademark")), demo: DEMO });
+  // ── NOTHING OF THE DEMO LANDS IN AN INSTALL, AND THAT IS CHECKED BEFORE ANYTHING IS WRITTEN ───────
+  //
+  // The demo keeps its signing secret in its base and `key issue --base` reads it from there, so a demo
+  // pointed at an install's directory would leave a secret where that install's own key command looks:
+  // every key issued afterwards would be signed with the demo's while the install's door verified with
+  // its own — a key that looks issued and is refused, with nothing said either way. The settings are
+  // READ here and never applied; a demo still takes nothing from them.
+  if (DEMO) {
+    const base = resolve(paths.base);
+    const inside = (p) => { const v = String(p ?? "").trim(); if (!v) return false; const r = resolve(v); return r === base || r.startsWith(base + sep); };
+    let settings = {};
+    try { settings = parseEnvFile(readFileSync(activeEnvPath(), "utf8")); } catch { /* no settings in force: nothing of an install to collide with */ }
+    const found = [];
+    if (inside(settings.CLEAROTRON_REPORTS_DIR)) found.push(`an install keeps its reports in ${settings.CLEAROTRON_REPORTS_DIR}`);
+    if (inside(settings.RECIPE_REPO_ROOT)) found.push(`an install keeps its saved searches in ${settings.RECIPE_REPO_ROOT}`);
+    if (inside(settings.CLEAROTRON_WORK_DIR)) found.push(`an install works in ${settings.CLEAROTRON_WORK_DIR}`);
+    if (existsSync(join(paths.base, ".env"))) found.push(`it holds a settings file, ${join(paths.base, ".env")}`);
+    if (!found.length && base === resolve(join(homedir(), "trademark"))) found.push("it is the directory an install is set up in by default");
+    // AN INSTALL NOBODY CONFIGURED still answers. `start --base <dir>` writes a guest list on every start
+    // and no settings at all, so an install somewhere of its own passes every check above. A guest list
+    // with no demo secret beside it is somebody's install; a demo's own base has both.
+    if (!found.length && existsSync(paths.grants) && !existsSync(demoTokenSecretPath(paths.base)))
+      found.push(`it holds a guest list, ${paths.grants}, and no demo of its own`);
+    if (found.length)
+      fatal(`--demo cannot run in ${paths.base}: ${found.join("; ")}.\n`
+        + "  The demo keeps its own data, and its own signing secret, in its base. Leaving those in an\n"
+        + "  install's directory would make keys issued for that install refuse at its door.\n"
+        + "  Run the demo without --base, or give it a directory of its own.");
+  }
   // ── THIS INSTALL'S FIRST START, read before this start writes either file that answers it ────────────
   //
   // The grants file and the config store's repository are both written further down, on every start
@@ -1171,7 +1207,15 @@ if (isMain) {
     return v;
   };
   const portalSecret = secretFor("PORTAL_SECRET");
-  const tokenSecret = secretFor("TRADEMARK_MCP_TOKEN_SECRET");
+  // A DEMO'S SIGNING SECRET IS KEPT IN ITS OWN BASE, so the key command it prints can sign for it; see
+  // `demoTokenSecret`. Every other secret a demo uses stays in memory.
+  const tokenSecret = DEMO
+    ? demoTokenSecret(paths.base, {
+      read: (f) => readFileSync(f, "utf8"),
+      write: (f, text) => { mkdirSync(dirname(f), { recursive: true }); writeSecretFile(f, text); },
+      mint: () => randomBytes(32).toString("base64url"),
+    })
+    : secretFor("TRADEMARK_MCP_TOKEN_SECRET");
   if (!process.env.PORTAL_LOCAL_USER) generated.PORTAL_LOCAL_USER = user;
   const stores = DEMO ? {} : storesForOtherReaders(paths);
 
@@ -1253,7 +1297,7 @@ if (isMain) {
         say(`  grants         ${paths.grants} named nobody, so ${user} was added: Run, Manage, access to everything`);
       if (seeded.changed.includes("organisation")) say(`                 organisation "${organisation}", filed there — rename it there too`);
       else if (seeded.changed.includes("person") && !Object.keys(seeded.grants.tenants ?? {}).length)
-        say(`                 no organisation named yet — \`${invocationPrefix()}clearotron start --organisation "<name>"\` files the first one`);
+        say(`                 no organisation named yet — \`${reachableCommand('start --organisation "<name>"')}\` files the first one`);
       // REPORTED, NOT REPAIRED. A file that names other people is somebody's decision, and adding this
       // address to it would give access to everything to an address nobody enrolled.
       if (seeded.unadmitted)
@@ -1464,25 +1508,9 @@ if (isMain) {
   // The same version goes into `<base>/program` (shared/permanent-install.mjs), BEFORE the services start
   // so the portal's connect rows name it too, and only when it is not there already. It never stops the
   // demo: if npm fails, the demo runs as before and says the line will not survive a cache clean.
-  let demoProgramRoot = null;
-  if (DEMO) {
-    const plan = demoProgramPlan({ base: paths.base });
-    if (plan?.current) demoProgramRoot = plan.root;
-    else if (plan && !plan.skip) {
-      say(`  program        copying clearotron ${plan.version} into ${plan.prefix}, so your assistant's connection survives npm cleaning its cache`);
-      // The npm that launched this, when npm says which: no second npm is guessed at.
-      const npmCli = process.env.npm_execpath;
-      const r = npmCli && existsSync(npmCli)
-        ? spawnSync(process.execPath, [npmCli, ...plan.npmArgs], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 })
-        : spawnSync("npm", plan.npmArgs, { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 });
-      if (r.status === 0 && existsSync(join(plan.root, "mcp-server", "server.mjs"))) demoProgramRoot = plan.root;
-      else {
-        const why = r.error ? r.error.message : String(r.stderr ?? "").trim().split("\n").pop() || `npm exited ${r.status}`;
-        say(`  program        could not be copied (${why}). The connect line below runs from npm's temporary cache,`);
-        say("                 so it stops working when npm cleans that cache; start the demo again to retry.");
-      }
-    }
-  }
+  // `clearotron demo` makes the copy before it starts this file, and starts this file FROM the copy, so
+  // there this finds nothing to do; it acts for a `start --demo` typed at npx directly.
+  const demoProgramRoot = DEMO ? ensureDemoProgram({ base: paths.base, say }) : null;
 
   const envs = childEnv({ ports, paths, user, portalSecret, tokenSecret, opsToken,
     localWorker: wantWorker, demo: DEMO, clientFence: declaredFence || null,
@@ -2192,12 +2220,26 @@ if (isMain) {
     if (adoptedClientDoor)
       say(`               Already running as ${CLIENT_DOOR_UNIT}; this start kept it, so existing keys still work.`);
     else
-      say(`               It refuses every caller until a key is issued: ${invocationPrefix()}clearotron key issue <email>`);
+      say(`               It refuses every caller until a key is issued: ${keyIssueCommand({ prefix: invocationPrefix(), demo: DEMO, user, base: paths.base, defaultBase: join(homedir(), "trademark") })}`);
   } else {
     say(`  Client door  NOT RUNNING on ${HOST}:${ports.client} — its output above says why. The portal and`);
     say("               the engine door are unaffected; a client assistant cannot connect until it is up.");
   }
   say("");
+  // ── WHAT `status` AND `stop` READ ABOUT THIS START ───────────────────────────────────────────────
+  //
+  // Both verbs knew only about background units, so with this start serving, `status` described units
+  // nobody installed and `stop` said nothing was running (measured on a published beta, 2026-09-11). The
+  // record is the address this banner just printed. It goes on every exit — Ctrl-C, a fatal refusal, a
+  // crash — and a start killed outright leaves a record whose process is gone, which the readers ignore.
+  try {
+    const forget = recordRunning({ pid: process.pid, demo: DEMO, base: paths.base, url: envs.url, host: HOST,
+      ports: { portal: ports.portal, mcp: ports.mcp, client: doorRunning ? ports.client : null },
+      startedAt: new Date().toISOString() });
+    process.on("exit", forget);
+  } catch (e) {
+    say(`  (\`status\` will not see this start: its record could not be written — ${String(e?.message ?? e)})`);
+  }
   // — THE BANNER TOLD THE SAME STORY ON EVERY START, and it was only true of the first.
   //
   // "printed once, above" describes what a FIRST start does. On every start after it the passphrase was
@@ -2289,17 +2331,35 @@ if (isMain) {
   // cannot succeed and given a service manager that is not on the machine and cannot be put there.
   // Reported from a real run. Same rule as the engine refusal above: do not name a route this platform
   // does not have.
-  const manager = backgroundManager();
-  if (manager) {
-    say(`  To get your prompt back instead, stop this and run  ${invoke("start")} --background`);
-    say(`  — same product, managed by ${manager}, and it survives logout.`);
-  } else {
-    say("  There is no background form on this platform: the product runs as long as this window does.");
-    say("  Leave it open and use a second terminal for the commands above.");
-  }
+  for (const line of backgroundOfferLines({ demo: DEMO, manager: backgroundManager(), start: invoke("start") })) say(line);
   say("");
 }
 
+/**
+ * The closing offer of a foreground start: how to get the prompt back, where there is a way.
+ *
+ * NOT IN A DEMO. The offer ran `start --background`, which set up a new, empty install in the reader's
+ * home — not the demo, its samples or its sign-in — and then failed where the user's systemd was not
+ * reachable (measured on a published beta, 2026-09-11). A demo has no background form, so it is not
+ * offered one. Where the offer stands, it names what it needs BEFORE the reader stops what is running.
+ * PURE.
+ */
+export function backgroundOfferLines({ demo = false, manager = null, start = "clearotron start" } = {}) {
+  if (demo) return [
+    "  The demo has no background form: it runs as long as this window does. Leave it open and use a",
+    "  second terminal for the commands above.",
+  ];
+  if (!manager) return [
+    "  There is no background form on this platform: the product runs as long as this window does.",
+    "  Leave it open and use a second terminal for the commands above.",
+  ];
+  return [
+    `  To get your prompt back instead, stop this and run  ${start} --background`,
+    `  — same product, managed by ${manager}, and it survives logout. It needs ${manager}'s user manager`,
+    "  reachable from this session; where it is not, that command says so and changes nothing you use.",
+  ];
+}
+
 /**
  * What a reader is told when a child this install cannot run without exits.
  *

package/bin/status.mjs

@@ -18,6 +18,7 @@ import { BACKGROUND_UNITS, resolvePorts } from "./start.mjs";
 import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // ONE KEY=value reader — what systemd actually reads
 import { CLIENT_DOOR_UNIT, clientDoorPort } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
+import { readRunning, probe } from "../shared/running-start.mjs";
 import { configStaleness, stalenessWarning, parseSystemdTimestamp } from "../driver/config-staleness.mjs";   // — F48
 
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
@@ -57,15 +58,34 @@ const startedEpochMs = (u) => {
     return parseSystemdTimestamp(line?.slice("ActiveEnterTimestamp=".length));
   } catch { return null; }
 };say("");
+// ── A FOREGROUND START ANSWERS HERE TOO ─────────────────────────────────────────────────────────────
+//
+// The README starts the product in a terminal, and this verb answered only for background units: with
+// everything up it printed a sentence about units the reader never installed (measured on a published
+// beta, 2026-09-11). The record gives the address `start` printed; the portal itself says whether it is up.
+const running = readRunning();
+for (const r of running) {
+  const what = r.demo ? "The demo" : "The product";
+  // The portal's liveness route, which answers without a session: the address itself asks for a sign-in
+  // and read as "not answering" over a portal that was up (driven 2026-09-11).
+  if (await probe(new URL("/portal/health", r.url).href)) say(`  ${what} is up, in the foreground — a terminal holds \`start\` (pid ${r.pid}); Ctrl-C there stops it.`);
+  else say(`  ${what} was started in the foreground (pid ${r.pid}), but its portal at ${r.url} is not answering.`);
+  say(`    Open         ${r.url}`);
+  say(`    Engine door  http://${r.host}:${r.ports.mcp}/mcp`);
+  if (r.ports.client) say(`    Client door  http://${r.host}:${r.ports.client}/mcp`);
+  say("");
+}
 let installed = 0;
 for (const u of BACKGROUND_UNITS) {
   if (!existsSync(join(UNIT_DIR, u))) continue;
   installed++;
   say(`  ${u.padEnd(34)} ${state(u)}`);
 }
-if (!installed) {
-  say("  No background units are installed — this box runs the product only while a terminal holds");
-  say(`  \`clearotron start\`. \`clearotron start --background\` is the form that survives the terminal.`);
+if (!installed && running.length) {
+  say("  No background units are installed.");
+} else if (!installed) {
+  say("  The product is not running: no terminal holds `start`, and no background units are installed.");
+  say(`  \`${invoke("start")}\` runs it in a terminal; \`${invoke("start")} --background\` runs it as services that survive logout.`);
 } else {
   // The ports come from the same resolver start uses, RESOLVED OVER THE UNITS' OWN FILE: the running
   // services read %h/.env via systemd, and this CLI's shell env may know nothing of it — the first