clearotron 0.3.0-beta.8 → 0.3.0

package/INSTALL.md

@@ -295,6 +295,71 @@ keeps working throughout.
 provider, so it is safe to run on any machine that has the repository. "Safe anywhere" is about spend,
 not about where it will run — on a packaged tree it refuses, as above.
 
+## 2a. Removing it
+
+An install is not one directory, so removing it is not one command. Everything it writes is listed here.
+Read the list before you delete anything: one of these directories holds your reports.
+
+**Stop it first.** If the product is running in a terminal, Ctrl-C in that terminal. If you installed the
+background services, `clearotron stop` stops them and removes their unit files. `clearotron status` says
+which of the two you have.
+
+**The program.** Installed globally, `npm rm -g clearotron` removes it. Installed by `clearotron install`
+(which is also what a demo run from `npx` leaves behind), it lives in two places under `~/.local`:
+
+```
+~/.local/lib/node_modules/clearotron
+~/.local/bin/clearotron
+```
+
+**The settings, and the keys.** `~/.config/clearotron/.env` holds this install's signing secrets, so
+deleting it invalidates every key it ever issued. Beside it: `~/.config/clearotron/token-denylist`, the
+list of keys you revoked, and `~/.config/clearotron/running`, which records a product running in a
+terminal and is rewritten on every start.
+
+**Your work.** The install keeps it all under one directory, `~/trademark` by default — wherever
+`CLEAROTRON_REPORTS_DIR`'s parent points if you moved it:
+
+```
+~/trademark/pool                              THE REPORTS. Every clearance this install delivered.
+~/trademark/workspace                         the working files of each run, including unfinished ones
+~/trademark/queue                             work ordered and not yet run
+~/trademark/outbox                            what the product prepared to send
+~/trademark/locks                             which runs are in flight
+~/trademark/config                            your companies, their projects and your saved searches
+~/trademark/config/recipes                    the saved searches themselves
+~/trademark/config/profiles                   the company profiles
+~/trademark/grants.json                       who may use this install
+~/trademark/portal-audit.log                  what the portal was asked to do
+~/trademark/portal-local-credential.json      the sign-in this install minted for you
+```
+
+**Keep the pool if you want the reports.** They are finished documents and nothing else reads them: move
+`~/trademark/pool` somewhere of your own and delete the rest. Deleting the pool deletes the clearances.
+
+**The demo, if you ran one.** `~/trademark-demo` holds the demo's own copy of everything above, including
+its own copy of the program under `~/trademark-demo/program`. It is one directory to remove and it shares
+nothing with an install.
+
+**The background services, if you installed them.** `clearotron stop` removes the four unit files; if you
+would rather see them, they are in `~/.config/systemd/user`:
+
+```
+clearotron-portal.service
+clearotron-mcp-face.service
+clearotron-worker.service
+clearotron-client-mcp.service
+```
+
+**And `~/.env`, which only a background install writes.** A service inherits nothing from the terminal
+that installed it, so `clearotron start --background` writes everything those services need into `~/.env`,
+mode 600 — your register credential, your research key and the engine's settings among it. It is not the
+same file as `~/.config/clearotron/.env`, which configures the product when you run it yourself. Delete
+both, or you leave a file of credentials in your home for services that no longer exist.
+
+Nothing else on the machine is ours: no system-wide files, no services outside your own user, and nothing
+in `/etc`, `/usr` or `/var`.
+
 ## 3. Configuration (environment)
 
 Runtime configuration is by environment variable, and there are two ways to supply them.

package/README.md

@@ -59,6 +59,9 @@ npx clearotron@beta install
 What each channel promises, and when a stable is cut: [docs/RELEASES.md](docs/RELEASES.md). If you are not
 sure, the first command is the one you want.
 
+Removing it later: **[INSTALL.md §2a](INSTALL.md#2a-removing-it)** lists every path an install writes, and
+says which one holds your reports so you can keep them deliberately.
+
 ## Quick start
 
 With it installed, check what it found before it does anything. `doctor` only reads — it writes nothing,

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

@@ -116,7 +116,7 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-p
 // one synopsis reader for every verb that prints one.
 import { usageBlock } from "../shared/usage-block.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
-import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // — ONE KEY=value reader; a second copy would drift from what systemd actually reads
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // — ONE KEY=value reader, taken from a leaf: the unit renderer re-exports this same function, and it is a COMMAND, so importing it from here would put a command in this binary's graph
 import { unitEnvironment, unitValue, couldNotDetermine } from "../driver/unit-environment.mjs";   // — F34: claim about the UNITS only from the units' own environment
 
 /**
@@ -1503,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`);

package/bin/start.mjs

@@ -118,15 +118,16 @@ import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "
 // — 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, reachableCommand } from "../shared/invocation.mjs";   // — the banner names the verb
-import { unitEnvPath } from "../shared/env-local.mjs";   // — the file the units read, named once
+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);
 
@@ -2176,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
@@ -2273,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

@@ -15,9 +15,10 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { BACKGROUND_UNITS, resolvePorts } from "./start.mjs";
-import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // ONE KEY=value reader — what systemd actually reads
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // ONE KEY=value reader — what systemd actually reads, taken from the leaf the unit renderer re-exports it from
 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

package/bin/stop.mjs

@@ -23,6 +23,7 @@ import { systemdSaid, looksLikeBusFailure, busRemedy, CAPTURE_STDERR } from "../
 import { BACKGROUND_UNITS } from "./start.mjs";
 import { CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
+import { readRunning } from "../shared/running-start.mjs";
 
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
 const say = (s = "") => console.log(s);
@@ -91,17 +92,31 @@ for (const u of BACKGROUND_UNITS) {
 }
 // THE COMMENT HERE ALREADY NAMED THE CAUSE AND SHRUGGED AT IT. If there is no user bus, the disables
 // above did not happen either — so this is where that is said.
-try {
-  execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR);
-} catch (e) {
-  const said = systemdSaid(e);
-  err(`  could not ask systemd to reload its units — ${said}`);
-  if (looksLikeBusFailure(said)) err(`\n${busRemedy()}\n`);
+// ONLY WHEN THERE WAS SOMETHING TO RELOAD. On a box with no unit installed the reload has nothing to do,
+// and asking anyway printed a bus error and `su` advice to a reader whose product was running in a
+// terminal — a WSL distribution without systemd meets exactly that (measured 2026-09-11).
+if (found) {
+  try {
+    execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR);
+  } catch (e) {
+    const said = systemdSaid(e);
+    err(`  could not ask systemd to reload its units — ${said}`);
+    if (looksLikeBusFailure(said)) err(`\n${busRemedy()}\n`);
+  }
 }
 
 if (!found) {
-  say("  Nothing was running in the background — no pinned unit is installed on this box.");
-  say("  Nothing to do, and nothing was changed.");
+  // A FOREGROUND START IS NOT "NOTHING RUNNING". It is not this verb's to stop — its terminal holds it —
+  // but saying nothing was running while it served is the answer that sent a reader looking elsewhere.
+  const foreground = readRunning();
+  if (foreground.length) {
+    say("  No background product is installed, but the product is running in the foreground:");
+    for (const r of foreground) say(`    ${r.demo ? "the demo" : "the product"} at ${r.url} (pid ${r.pid})`);
+    say("  Ctrl-C in the terminal that holds it stops it. This verb stops only what `start --background` installed.");
+  } else {
+    say("  Nothing was running in the background — no pinned unit is installed on this box.");
+    say("  Nothing to do, and nothing was changed.");
+  }
 } else if (failures.length) {
   // THE SENTENCE THAT WAS WRONG. "The background product is stopped and the box runs nothing again" was
   // printed unconditionally — including on the run where four services stayed up. A reader who is told

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "6c0b09af72bcc7b6e57f5aa268ffb29361d1eaab",
-  "version": "0.3.0-beta.8"
+  "commit": "cd86797b655d82bc021e2ada72cbacdc261174dc",
+  "version": "0.3.0"
 }

package/docs/RELEASES.md

@@ -54,5 +54,5 @@ Downgrading is an ordinary install of the older version. Your configuration and
 by either — they live outside the package — so moving between channels is not a migration.
 
 Every version's notes are on the [releases page](https://github.com/CordilleraSarl/clearotron/releases)
-and in `CHANGELOG.md`, grouped New / Fixed / For operators. A beta's notes are the same notes; the stable
+and in `CHANGELOG.md`, grouped Before you upgrade / New / Fixed / For operators. A beta's notes are the same notes; the stable
 that follows aggregates all of them into one entry.

package/driver/CHANGELOG.md

@@ -1,5 +1,49 @@
 # clearotron-driver
 
+## 0.3.0
+
+### Minor Changes
+
+- d2afa5e: Before you upgrade: Name every person who uses your installation in the file that lists who may sign in, or the portal will not start. That file is in your install folder.
+- d2afa5e: New: Switch between companies from any screen, and set a new one up in the browser.
+- d2afa5e: New: Add people from the portal, and give each the right to run clearances, to manage people and companies, or both.
+- d2afa5e: New: Every register finding in a report links to the trade mark office's own page for that record.
+- d2afa5e: New: A clearance records any territory it could not cover, so a partial search never reads as a complete one.
+- d2afa5e: New: Connect Clearotron to your own AI assistant — Claude Code, Codex, or ChatGPT — on your computer or a shared server.
+- d2afa5e: New: A saved search is available in every company, in the portal and in your AI assistant.
+- d2afa5e: New: Check a risk framework for errors before it rates a clearance, and point a company at its own.
+- d2afa5e: New: Group companies under an organisation, each with its own daily limit on clearances.
+- d2afa5e: New: Clearotron installs to a fixed location, so the commands it prints and your AI assistant's connection keep working.
+- d2afa5e: New: `clearotron update` moves an installation, beta included, to the current release.
+
+### Patch Changes
+
+- d2afa5e: Fixed: You sign in, open your companies, and run your first clearance on a new installation.
+- d2afa5e: Fixed: The demo reads and writes only its own companies, reports, and saved searches.
+- d2afa5e: Fixed: `clearotron doctor` checks what a clearance needs, so an installation it clears can run one.
+- d2afa5e: Fixed: A key you paste at a yes-or-no question stays off the screen and out of your command history.
+- d2afa5e: Fixed: Clearotron stays signed in to a paid Codex plan when Codex renews the sign-in.
+- d2afa5e: Fixed: The dashboard shows only the chosen company's clearances, and keeps the filters on screen.
+- d2afa5e: Fixed: The Stop button ends a run before its report goes out, and its dialog says what stopping does.
+- d2afa5e: Fixed: A knockout report names the filings behind each finding, and marks the reviewer's notes as reference.
+
+## 0.3.0-beta.10
+
+### Patch Changes
+
+- fd3a4f7: Fixed: A portal address that does not exist now says so wherever it is. Addresses under the admin path used to show the Global config screen.
+- fd3a4f7: New: The install guide now says how to remove Clearotron, naming every path it writes and which one holds your reports.
+
+## 0.3.0-beta.9
+
+### Patch Changes
+
+- 86061f4: Fixed: Commands printed while running from npx name the published version, so they still work after npm cleans its cache.
+- ab9dc2d: Fixed: When the engine cannot answer "Describe it", the page names the check that finds out why. It says "just now" only for a usage limit.
+- ab9dc2d: Fixed: `clearotron status` says whether a product started in a terminal is up, and on which addresses. `clearotron stop` says how to stop it.
+- ab9dc2d: Fixed: The demo no longer offers `start --background`, which set up an empty install in your home instead of running the demo.
+- ab9dc2d: Fixed: The key command the demo prints issues a key the demo's client door accepts, run exactly as printed.
+
 ## 0.3.0-beta.8
 
 ### Patch Changes

package/driver/compose-read.mjs

@@ -325,7 +325,26 @@ export function jsonFromTurnText(text) {
   return null;
 }
 
-export function makeComposeReader({ turn, now = () => new Date() } = {}) {
+/**
+ * What the page says when the engine did not answer a read.
+ *
+ * "JUST NOW" ONLY WHERE IT IS TRUE. Every failed turn said the reader "could not reach the engine just
+ * now", and on a fresh install whose engine was not signed in that sent a stranger to press the button
+ * again, forever: the failure was the sign-in, which no retry changes (measured on a published beta,
+ * 2026-09-11). A rate limit is the one failure known to pass, so it alone says so, with its reset time
+ * when the engine gave one. Everything else names the check that finds the cause — `checkCommand`, in the
+ * reader's own invocation and with no machine path, because the page is not a place to print one.
+ */
+export function engineFailureMessage(t, { checkCommand = "clearotron doctor --probe-engine" } = {}) {
+  if (t?.rateLimited) {
+    const at = t.resetsAt ? new Date(t.resetsAt) : null;
+    const when = at && !Number.isNaN(at.getTime()) ? ` It resets at ${at.toISOString().slice(11, 16)} UTC.` : "";
+    return `The engine is at its usage limit just now.${when} Try again then, or set the search up below.`;
+  }
+  return `The request could not be read: the engine did not answer it. \`${checkCommand}\` finds out why — set the search up below meanwhile.`;
+}
+
+export function makeComposeReader({ turn, now = () => new Date(), checkCommand } = {}) {
   if (typeof turn !== "function") return null;
   return async function read(brief) {
     const text = String(brief ?? "").trim();
@@ -361,7 +380,7 @@ export function makeComposeReader({ turn, now = () => new Date() } = {}) {
         + `${JSON.stringify(READ_SCHEMA)}\n\nThe brief:\n${text}`,
     });
     if (!t?.ok) {
-      return { ok: false, error: "engine", message: "The reader could not reach the engine just now — set the search up below.",
+      return { ok: false, error: "engine", message: engineFailureMessage(t, { ...(checkCommand ? { checkCommand } : {}) }),
         cause: t?.cause ?? "the engine turn did not complete", vendor: t?.vendor ?? null, authMode: t?.authMode ?? null,
         engine: t?.engine ?? null, model: t?.model ?? null };
     }

package/driver/engine/jx-turn.mjs

@@ -94,7 +94,10 @@ export function readJxTuple(tuple, { vendor, authMode, engine }) {
   if (tuple?.killed || tuple?.signals?.stalled)
     return { ok: false, cause: "the engine turn was killed before it answered (stall or wall)", truncationObservable: observable, ...base };
   if (tuple?.signals?.rateLimited)
-    return { ok: false, cause: "the engine turn was rate-limited", truncationObservable: observable, ...base };
+    // FLAGGED, not only described: a rate limit is the one failure a caller may call passing, and it
+    // needs to know that without parsing this sentence. `resetsAt` is the adapter's, when it read one.
+    return { ok: false, cause: "the engine turn was rate-limited", rateLimited: true, resetsAt: tuple?.signals?.resetsAt ?? null,
+      truncationObservable: observable, ...base };
   if (tuple?.code !== 0 || tuple?.json?.status !== "ok")
     return { ok: false, cause: `the engine turn did not complete cleanly (code ${tuple?.code ?? "?"}, status ${tuple?.json?.status ?? "none"})`,
       truncationObservable: observable, ...base };

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.8",
+  "version": "0.3.0",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/portal-service.mjs

@@ -1590,7 +1590,10 @@ export function makePortalService({
           // A provider outage is not a portal fault and must not read as one. The composer shows the
           // sentence and keeps every field the user already typed — the brief is still in the box.
           audit({ event: "compose-read", by: principal.email, ok: false, error: String(e?.message ?? e) });
-          return { status: 502, json: { code: "read_failed", error: "The reader is not answering just now — set the search up below." } };
+          // NOT "just now": a throw says nothing about whether it will pass, and that wording sent a reader
+          // back to the button for a failure no retry fixes. It names the check instead.
+          return { status: 502, json: { code: "read_failed",
+            error: `The request could not be read: the reader failed. \`${browserCommand("doctor --probe-engine")}\` finds out why — set the search up below meanwhile.` } };
         }
         // Length, never content. A brief is client material — whose mark, for whose product, before
         // whose deadline — and an audit log is a different disclosure surface from a run store.
@@ -4711,7 +4714,8 @@ const PORT = PORT_CHOICE.port;
         return null;
       }
       log(`brief reading ON — engine=${runner.engine} billing=${runner.authMode} model=${model}`);
-      return makeComposeReader({ turn: runner.turn });
+      // The check a failed read points at, as a reader types it, with no path of this machine in it.
+      return makeComposeReader({ turn: runner.turn, checkCommand: browserCommand("doctor --probe-engine") });
     } catch (e) {
       // A missing dependency or a bad key shape must not stop the portal booting: everything else on
       // this service is the load-bearing product, and the composer degrades to exactly what it did