clearotron 0.3.0-beta.6 → 0.3.0-beta.8

package/.env.example

@@ -561,8 +561,9 @@ CLEAROTRON_DEMO_PROFILES=
 # Your organisation's name. `npm run setup` asks for it (and, on a local install, not for a 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.
+# grants file holds the name and renaming is an edit there. The portal also reads it, to name the
+# organisation on its top bar and on its sign-in refusal page. 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 and shared/brand.mjs.
 # effect: deployment
 CLEAROTRON_ORGANISATION_NAME=

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/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
@@ -1548,9 +1558,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 +1901,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 +2235,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 +2319,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 +2338,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 +3976,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,6 +111,7 @@ 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 { 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
@@ -122,7 +123,7 @@ 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 { 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 { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
@@ -756,6 +757,10 @@ export function childEnv({ ports, paths, user, portalSecret, tokenSecret, opsTok
       // already wrong for a process that is not the portal.
       ...(demo ? {
         CLEAROTRON_DEMO: "1",
+        // A DEMO NAMES NO ORGANISATION. The portal reads this to name the one running the install, on its
+        // top bar and its sign-in refusal page, and an exported value is the reader's real organisation.
+        // The portal's alone: no door names an organisation, and the doors stay as a live install's.
+        CLEAROTRON_ORGANISATION_NAME: "",
         // AND THE SIGN-IN CREDENTIAL LIVES IN THE DEMO'S OWN BASE. Without this it defaults to
         // ~/.cordillera/portal-local-credential.json — shared with every install on the box — and the
         // demo then inherits a digest minted for somebody else's address: the portal prints "the
@@ -1248,7 +1253,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)
@@ -1389,8 +1394,9 @@ if (isMain) {
     const { publishSource, seedDemoRuns } = await import("../driver/demo-container.mjs");
     const seed = await seedPool({ pool: paths.pool, examplesDir: publishSource(join(REPO, "demo"), { repoRoot: REPO }), republish: republishRun });
     // AND AS RUNS, so the assistant this demo's connect line wires has them to list, brief and open. Under
-    // the demo's own workspace only: nothing of it reaches an install started afterwards.
-    const runs = seedDemoRuns({ workspace: paths.workspace, examplesDir: join(REPO, "demo") });
+    // the demo's own workspace only: nothing of it reaches an install started afterwards. Their report
+    // links are stamped with this portal's address, the one the Open line prints.
+    const runs = seedDemoRuns({ workspace: paths.workspace, examplesDir: join(REPO, "demo"), portalOrigin: `http://${HOST}:${ports.portal}` });
     if (runs.seeded.length) say(`  runs           ${runs.seeded.length} sample run(s) your assistant can list, brief and open`);
     // WHAT WAS ALREADY THERE IS SAID TOO. This branch used to run only when the pool
     // was empty; it now tops a stale pool up to the package's set, so "seeded 1" on an upgrade is a fact
@@ -1451,6 +1457,17 @@ if (isMain) {
   // the file the verb resets is the file the portal reads. A demo keeps its own, by layout (childEnv).
   const { installCredential } = await import("../driver/portal-local-auth.mjs");
   const signIn = DEMO ? null : installCredential({ base: paths.base, env: process.env, firstStart: firstStartOfThisInstall });
+  // ── A DEMO RUN FROM NPX KEEPS ITS OWN COPY OF THE PROGRAM ───────────────────────────────────────────
+  //
+  // Its connect line launched the connector from npm's cache, which npm deletes when it cleans up, so an
+  // assistant registered with it lost the demo without a word (measured on a published beta, 2026-09-11).
+  // 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.
+  // `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,
     credential: signIn && signIn.source !== "shared" ? signIn.path : null });
@@ -2233,7 +2250,8 @@ if (isMain) {
   // and a line of instruction with more than one author drifts silently.
   // THE WORKSPACE AND POOL THE SERVICES WERE HANDED, not this process's environment: a demo reads no env
   // file, so its own line named no workspace and the connector fell back to the real install's.
-  const connect = stdioConnectOffer({ workDir: paths.workspace, reportsDir: paths.pool });
+  // A demo run from npx names its own copy of the program, which a cache clean does not remove.
+  const connect = stdioConnectOffer({ workDir: paths.workspace, reportsDir: paths.pool, ...(demoProgramRoot ? { installRoot: demoProgramRoot } : {}) });
   say("  Connect your assistant to this install — one line, no address and no sign-in:");
   say("");
   say(`    ${connect.command}`);

package/build-info.json

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

package/demo/full-country-search/run/status.json

@@ -27,7 +27,7 @@
   "stepTotal": 9,
   "lastStage": "publish",
   "verdict": "CONDITIONAL",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014fullcountrysearch-venqori-2026-09-03-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014fullcountrysearch-venqori-2026-09-03-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-03T18:06:17.281Z",

package/demo/global-preliminary-search/run/status.json

@@ -27,7 +27,7 @@
   "stepTotal": 9,
   "lastStage": "publish",
   "verdict": "CONDITIONAL",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014globalpreliminarysearch-venqori-2026-09-02-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014globalpreliminarysearch-venqori-2026-09-02-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-02T17:33:15.625Z",

package/demo/knockout-search/run/email-body.md

@@ -1,3 +1,3 @@
-<p style="font-family:Calibri,sans-serif;font-size:11pt">Knockout trademark review — DEMO-2014-knockout-search: <b>1 mark</b>, worst band <b style="color:#2f55a4">Low</b>. <a href="https://test-trademark.cordillera.ch/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/report.html">Open the full report</a> · <a href="https://test-trademark.cordillera.ch/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/audit.xlsx">audit workbook</a>.</p>
+<p style="font-family:Calibri,sans-serif;font-size:11pt">Knockout trademark review — DEMO-2014-knockout-search: <b>1 mark</b>, worst band <b style="color:#2f55a4">Low</b>. <a href="/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/">Open the full report</a> · <a href="/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/audit.xlsx">audit workbook</a>.</p>
 <ul style="font-family:Calibri,sans-serif;font-size:11pt"><li><b>VENQORI</b>: <b style="color:#2f55a4">Low</b> — Classes 9, 42, 41 — Register filings (classes 9, 42, 41): 0 identical, 0 containing, 0 on close variations.</li></ul>
 <p style="font-family:Calibri,sans-serif;font-size:11pt"><i>Ratings reflect our common law assessment. Register analysis may adjust ratings in either direction.</i></p>

package/demo/knockout-search/run/status.json

@@ -33,7 +33,7 @@
   "stepN": 6,
   "stepTotal": 6,
   "verdict": "Low",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-02T21:46:53.238Z",
@@ -254,7 +254,7 @@
   "reports": [
     {
       "mark": "VENQORI",
-      "url": "https://test-trademark.cordillera.ch/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/report.html"
+      "url": "/portal/report/tmpdemo2014knockoutsearch-venqori-2026-09-02-sample-capture/"
     }
   ],
   "sendPending": true,

package/demo/multi-country-focus-search/run/status.json

@@ -27,7 +27,7 @@
   "stepTotal": 9,
   "lastStage": "publish",
   "verdict": "CONDITIONAL",
-  "url": "https://test-trademark.cordillera.ch/tmpdemo2014multicountryfocussearch-venqori-2026-09-02-sample-capture/report.html",
+  "url": "/portal/report/tmpdemo2014multicountryfocussearch-venqori-2026-09-02-sample-capture/",
   "failedStage": null,
   "reason": null,
   "deliveredAt": "2026-09-02T19:51:48.801Z",

package/docs/architecture/04-configuration-reference.md

@@ -285,7 +285,7 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `CLEAROTRON_DEMO` | unset | `1` puts this install in the DEMO posture. **Ordering is real**: the four products are listed and orderable, the form, the plan and the confirmation are the product's own, and the confirmation resolves to a finished report that already exists rather than dispatching — no engine turn, no register call, no queue entry, no run directory (ruling 2026-08-31, superseding the greyed-control ruling of the same day). A product the demo carries no finished report for refuses and names which one. It also re-aims two boot warnings written for an operator of a real deployment at the visitor who is not one, from one place (`driver/demo-posture.mjs`). **Set by `npx clearotron demo`, not by an operator** — it is passed explicitly to the two processes that have a reason to know (the portal and the MCP door; the worker is not told, because a demo never queues anything for it to drain), and those run with `CLEAROTRON_NO_ENV_FILE=1`, so a stray `.env` can neither put a live install into demo mode nor take a demo out of one. Anything but the literal `1` is not a demo. Replaces `PORTAL_DEMO`, which named only one of the processes that has to know. |
 | `CLEAROTRON_TEST_FIXTURE_PROFILES` | unset | `1` makes the profile loader return the three suite fixtures, which are refused from every roster otherwise. Set by `scripts/test-run.mjs`, never by an operator; an explicit `includeTestFixtures` argument beats it. Effect class `harness`; the full contract is its row in `.env.example`. |
 | `CLEAROTRON_DEMO_PROFILES` | unset | `1` makes the profile loader return the bundled demo account, which a fresh install does not resolve (ruling 2026-09-08). Set by `clearotron demo`, `start --demo` and the suite runner, never by an operator. The gate is on the bundled layer, so a deployment's own configured store keeps its `demoData` accounts either way. Effect class `harness`; the full contract is its row in `.env.example`. |
-| `CLEAROTRON_ORGANISATION_NAME` | unset | Your organisation's name, written quoted by `npx clearotron install`, which asks for it and not for a sign-in address. 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 ⇒ no organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a demo never reads it. Effect class `deployment`; the full contract is its row in `.env.example`. |
+| `CLEAROTRON_ORGANISATION_NAME` | unset | Your organisation's name, written quoted by `npx clearotron install`, which asks for it and not for a sign-in address. 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 and renaming is an edit there. The portal also reads it, to name the organisation on its top bar and on its sign-in refusal page. Unset ⇒ no organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a demo never reads it. Effect class `deployment`; the full contract is its row in `.env.example`. |
 | `PORTAL_LOCAL_CREDENTIAL` | `~/.cordillera/portal-local-credential.json` | Where local sign-in keeps its passphrase DIGEST. `clearotron start` points it inside the install's own base directory for a new install, so it mints its own passphrase instead of adopting a digest another install left; an install that has been signing in with the shared file keeps it. `npx clearotron demo` always points it inside the demo's own base directory and mints a new passphrase there on every start, so a demo never inherits a digest minted for another address, and removing the demo stays one `rm -rf`. |
 | `PORTAL_LOCAL_PASSPHRASE` | unset | **NEVER set this in a file.** An internal one-shot handoff, not an operator control: on a first FOREGROUND start the supervisor mints the passphrase and hands it to the portal it spawns *at the spawn call*, so the closing summary can print the value beside the address rather than sending a first-time reader back into eleven startup log lines for the one value in this product that cannot be read back. It is deliberately absent from the composed child environments, because that composition is what `--background` writes into the units' env file — a passphrase there would be a permanent plaintext copy on disk and the product's own sentence, "it is stored only as a digest", would stop being true. Setting it in any env file recreates exactly that. Lost passphrase: `clearotron passphrase --reset`. |
 | `PORTAL_URL` | `http://127.0.0.1:18802`, or built from `PORTAL_SERVICE_HOST`/`PORTAL_SERVICE_PORT` | Where the deploy tick's live-surface check expects to reach the portal. |

package/driver/CHANGELOG.md

@@ -1,5 +1,23 @@
 # clearotron-driver
 
+## 0.3.0-beta.8
+
+### Patch Changes
+
+- 9181d6a: Fixed: Commands the install, start and the New company screen print now run as printed, from any directory and after npm cleans its cache.
+- 0d75b4a: Fixed: A demo started with npx prints commands that keep working after npm cleans its cache.
+- 9181d6a: Fixed: Doctor, run before the first start, describes the local sign-in that start brings up, and drops checkout-only warnings on a packaged install.
+- 91888b2: Fixed: The package no longer names the hosted service's own hostnames; a deployment names its own.
+- 9181d6a: Fixed: The README installs with `npx clearotron install`, which needs no root, and no longer says the demo opens a browser.
+
+## 0.3.0-beta.7
+
+### Patch Changes
+
+- c5744bf: Fixed: A demo started with npx keeps its assistant connection working after npm cleans its cache.
+- c5744bf: Fixed: An assistant connected to the demo now opens each sample report on the demo's own portal, not on another server.
+- c5744bf: Fixed: The portal names the organisation setup recorded, and the product keeps its own name beside it.
+
 ## 0.3.0-beta.6
 
 ### Patch Changes

package/driver/demo-container.mjs

@@ -23,7 +23,7 @@
 // stage apart. This module is the single answer. `cut/` cannot import it (that directory does not travel
 // and this one does), so the pack gate restates the disjunction and its own test pins the two together.
 
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 
@@ -89,9 +89,17 @@ export function publishSource(dir, { repoRoot, tmp = tmpdir() } = {}) {
  * anywhere else, so a real install started afterwards sees none of it (the demo is its own install).
  *
  * Copied, never linked: a connector reading a run may write beside it, and `demo/` is tracked. A run
- * already in place is left alone, so a visitor's second start changes nothing.
+ * already in place is not copied again, so a visitor's second start changes nothing but its links.
+ *
+ * ITS REPORT LINKS POINT AT THIS DEMO'S PORTAL. Each sample's `status.json` carried the report URL it was
+ * stamped with where it was captured, a test instance's address, and the connector hands a run's `url` to
+ * the assistant as-is, so an assistant asked to open a demo report sent the person to that host (measured
+ * on a published beta, 2026-09-11). The tracked samples now carry the portal's own route,
+ * `/portal/report/<runId>/`, with no host, and each copy here is stamped with `portalOrigin`, the demo
+ * portal's address. Stamped on EVERY start, the copies already in place included: `--port` moves the
+ * portal, and a copy laid down by an earlier version still carries the old host.
  */
-export function seedDemoRuns({ workspace, examplesDir }) {
+export function seedDemoRuns({ workspace, examplesDir, portalOrigin = null }) {
   const seeded = [], already = [];
   for (const name of demoChildren(examplesDir)) {
     const run = join(examplesDir, name, "run");
@@ -99,10 +107,37 @@ export function seedDemoRuns({ workspace, examplesDir }) {
     try { s = JSON.parse(readFileSync(join(run, "status.json"), "utf8")); } catch { continue; }
     if (!s?.slug || !s?.codename || !s?.date) continue;
     const dir = join(workspace, `workspace-${s.agent || "clawdi"}`, "studio", "prelim-search", s.slug, `${s.date}-${s.codename}`);
-    if (existsSync(join(dir, "status.json"))) { already.push(s.runId); continue; }
-    mkdirSync(dirname(dir), { recursive: true });
-    cpSync(run, dir, { recursive: true });
-    seeded.push(s.runId);
+    if (existsSync(join(dir, "status.json"))) already.push(s.runId);
+    else {
+      mkdirSync(dirname(dir), { recursive: true });
+      cpSync(run, dir, { recursive: true });
+      seeded.push(s.runId);
+    }
+    if (portalOrigin) stampReportLinks(join(dir, "status.json"), portalOrigin);
   }
   return { seeded, already };
 }
+
+/** The portal route that serves a run's report: the one `scanAccountRuns` hands the portal's own list. */
+export const reportRoute = (runId) => `/portal/report/${encodeURIComponent(runId)}/`;
+
+/**
+ * Point a seeded run's report links at `origin`. A link already on the portal's route keeps its path; any
+ * other (the host an older sample carried) becomes the run's own route. Written only when something moved.
+ */
+export function stampReportLinks(statusFile, origin) {
+  let s;
+  try { s = JSON.parse(readFileSync(statusFile, "utf8")); } catch { return false; }
+  if (!s?.runId) return false;
+  const base = String(origin).replace(/\/+$/, "");
+  const local = (url) => {
+    const path = String(url ?? "").replace(/^https?:\/\/[^/]+/, "");
+    return `${base}${path.startsWith("/portal/report/") ? path : reportRoute(s.runId)}`;
+  };
+  const next = { ...s, url: local(s.url) };
+  if (Array.isArray(s.reports)) next.reports = s.reports.map((r) => (r && typeof r === "object" ? { ...r, url: local(r.url) } : r));
+  const text = `${JSON.stringify(next, null, 2)}\n`;
+  if (text === `${JSON.stringify(s, null, 2)}\n`) return false;
+  writeFileSync(statusFile, text);
+  return true;
+}

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "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

@@ -38,10 +38,9 @@ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { storeInRepo, storeOutsideRepoMessage, makeCommittableAudit, resolveStoreRepoRoot, makeStoreCommit } from "../shared/store-in-repo.mjs";   //,
 import { customerStoreDir, customerStoreLine } from "../shared/customer-store.mjs";   // — one store for the surface and the runs
 import { clientFailureNote } from "../shared/client-failure-note.mjs";   // — one sentence, three surfaces
-import { bareInvocation, invocationPrefix, installRoute } from "../shared/invocation.mjs";   // — and why this one surface is by NAME
+import { bareInvocation, browserCommand, invocationPrefix, installRoute, npxVersionOf } from "../shared/invocation.mjs";   // — and why this one surface is by NAME
 import { stdioConnectOffer, stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";   // — ONE author for the connect route
 import { isWsl } from "../shared/wsl.mjs";   // — on WSL, the connect lines say where they run
-import { inNpxCache, ownVersion } from "../shared/permanent-install.mjs";   // — a demo from npx is reset through npx
 import { connectOffers, offersForWire } from "../shared/connect-clients.mjs";                 // — ONE table, resolved server-side
 
 /**
@@ -1534,6 +1533,10 @@ export function makePortalService({
           // half its readers. A WORD, never a command line and never a prefix: `invocationForm` can
           // answer with this machine's absolute path, and this value is rendered in a browser.
           setupRoute: installRoute(),
+          // THE COMMAND THAT FILES AN ORGANISATION, for the screen that cannot create a company without one.
+          // `browserCommand`'s rule: no path on this machine, and from npx's cache the published version
+          // rather than a bare name that reader does not have.
+          organisationCommand: browserCommand('start --organisation "<name>"'),
           // — a button that always fails must not render as available. The reason is
           // operator-shaped and staff-only; a client reads the generic sentence the button carries.
           controls: { stop: { available: stopControl.available !== false,
@@ -4838,7 +4841,7 @@ const PORT = PORT_CHOICE.port;
       attempts: makeAttemptLimiter({ max: 10, windowMs: 5 * 60 * 1000 }),
       // The sign-in page's recovery line. It resets the file this portal reads, and names no path on this
       // machine, because the page is read before anyone has signed in (signInResetCommand says how).
-      resetCommand: signInResetCommand({ credentialPath, npxVersion: inNpxCache() ? ownVersion() : null }),
+      resetCommand: signInResetCommand({ credentialPath, npxVersion: npxVersionOf() }),
     };
   })();
 

package/driver/suite-census.json

@@ -970,9 +970,9 @@
           "todos": 0
         },
         "an-install-from-npx-moves-out-of-the-cache.test.mjs": {
-          "tests": 8,
-          "asserts": 45,
-          "skips": 4,
+          "tests": 13,
+          "asserts": 78,
+          "skips": 7,
           "todos": 0
         },
         "an-mcp-route-says-which-challenge-it-answers-with.test.mjs": {
@@ -2745,6 +2745,12 @@
           "skips": 0,
           "todos": 0
         },
+        "no-internal-hostname-ships-in-the-package.test.mjs": {
+          "tests": 1,
+          "asserts": 4,
+          "skips": 0,
+          "todos": 0
+        },
         "no-nul-bytes.test.mjs": {
           "tests": 3,
           "asserts": 7,
@@ -3089,7 +3095,7 @@
         },
         "portal-service.test.mjs": {
           "tests": 124,
-          "asserts": 670,
+          "asserts": 671,
           "skips": 1,
           "todos": 0
         },
@@ -4408,8 +4414,8 @@
           "todos": 0
         },
         "the-bar-names-no-organisation-nobody-named.test.mjs": {
-          "tests": 4,
-          "asserts": 7,
+          "tests": 6,
+          "asserts": 13,
           "skips": 0,
           "todos": 0
         },
@@ -4503,6 +4509,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-demo-links-its-reports-to-its-own-portal.test.mjs": {
+          "tests": 3,
+          "asserts": 13,
+          "skips": 0,
+          "todos": 0
+        },
         "the-door-answers-the-address-it-advertises.test.mjs": {
           "tests": 9,
           "asserts": 37,
@@ -4575,6 +4587,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-first-hour-reads-true.test.mjs": {
+          "tests": 8,
+          "asserts": 41,
+          "skips": 0,
+          "todos": 0
+        },
         "the-fold-receipt-names-the-model.test.mjs": {
           "tests": 5,
           "asserts": 11,

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-artifacts-mcp
 
+## 0.3.0-beta.8
+
+No changes in this release.
+
+## 0.3.0-beta.7
+
+No changes in this release.
+
 ## 0.3.0-beta.6
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/dist/assets/{index-DBUVdQT-.js → index-qes7gLpM.js}

@@ -10508,6 +10508,7 @@ var api = {
 		}),
 		accountOrgs: Object.fromEntries(Object.entries(asRecord(b["accountOrgs"])).filter(([, v]) => typeof v === "string" && v)),
 		genericOrgs: asArray(b["genericOrgs"]).filter((o) => typeof o === "string" && o.length > 0),
+		organisationCommand: asString(b["organisationCommand"]) || "clearotron start --organisation \"<name>\"",
 		email: asString(b["email"]) ?? "",
 		accounts: asArray(b["accounts"]).filter((a) => typeof a === "string"),
 		allAccounts: b["accounts"] === "*",
@@ -19106,7 +19107,7 @@ function NewCompany({ ctx }) {
 		if (!raw.trim()) return [];
 		return parseLines(raw, spec.commaSeparated ?? false).filter((e) => !spec.item.ok(e));
 	});
-	const unmet = !typedName ? "Needs a name." : !key ? "Needs a key — type one below." : !orgChosen ? orgsHeld.length === 0 ? "No organisation is filed on this install yet. File one with: clearotron start --organisation \"<name>\"" : "Choose the organisation it belongs to." : refusedEntries.length ? `${refusedEntries.join(", ")} cannot be searched — fix or remove ${refusedEntries.length === 1 ? "it" : "them"}.` : null;
+	const unmet = !typedName ? "Needs a name." : !key ? "Needs a key — type one below." : !orgChosen ? orgsHeld.length === 0 ? `No organisation is filed on this install yet. File one with: ${ctx.me.organisationCommand}` : "Choose the organisation it belongs to." : refusedEntries.length ? `${refusedEntries.join(", ")} cannot be searched — fix or remove ${refusedEntries.length === 1 ? "it" : "them"}.` : null;
 	async function create() {
 		if (unmet || busy) return;
 		setBusy(true);

package/portal-ui/dist/index.html

@@ -49,7 +49,7 @@
     -->
     <link rel="preconnect" href="https://api.fontshare.com" crossorigin />
     <link href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700,900&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/portal/assets/index-DBUVdQT-.js"></script>
+    <script type="module" crossorigin src="/portal/assets/index-qes7gLpM.js"></script>
     <link rel="stylesheet" crossorigin href="/portal/assets/index-Cv-E_agg.css">
   </head>
   <body>

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0-beta.8
+
+No changes in this release.
+
+## 0.3.0-beta.7
+
+No changes in this release.
+
 ## 0.3.0-beta.6
 
 No changes in this release.

package/providers/oauth-mcp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",

package/shared/access-audience.mjs

@@ -135,13 +135,14 @@ export function readAudience({ location = "", status = null, error = null, wwwAu
   if (error) return { kind: "unreachable", why: String(error?.message ?? error).slice(0, 200) };
   // ── THREE DOORS, NOT ONE ────────────────────────────────────────────────────────────────────────
   //
-  // This returned `not-fronted` for every response with no redirect, and measured against production's
-  // four configured hostnames that one label covered three materially different states:
+  // This returned `not-fronted` for every response with no redirect, and measured against a production
+  // deployment's four configured hostnames that one label covered three materially different states
+  // (the hosts are written here as placeholders; a deployment names its own):
   //
-  //   trademark.cordillera.ch        302  redirect present  → audience read, kid agrees
-  //   mcp.cordillera.ch/mcp          401  no redirect       → not-fronted   ← FALSE, it IS fronted
-  //   clients-mcp.cordillera.ch/mcp  401  no redirect       → not-fronted   ← FALSE, it IS fronted
-  //   agent-mcp.cordillera.ch/mcp    502  no redirect       → not-fronted   ← an origin fault
+  //   portal.example.com             302  redirect present  → audience read, kid agrees
+  //   mcp.example.com/mcp            401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   clients-mcp.example.com/mcp    401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   agent-mcp.example.com/mcp      502  no redirect       → not-fronted   ← an origin fault
   //
   // None of these was a false pass — every one returned ok:false, which is the property that matters
   // most and is untouched. It was a WRONG DIAGNOSIS on a safe failure, and the cost is a reader's hour

package/shared/brand.mjs

@@ -87,10 +87,14 @@ export const BRAND = {
  * installation, which on a fresh install has no answer, and answering it with the product's name puts
  * "Organisation: Clearotron" on the top bar of every install that never set it.
  *
- * Null rather than an empty string, so a caller cannot render it by accident. Nothing sets the variable
- * today; setup gains the question that will.
+ * Null rather than an empty string, so a caller cannot render it by accident.
+ *
+ * ITS OWN SETTING, `CLEAROTRON_ORGANISATION_NAME`, the one setup writes. This read `CLEAROTRON_BRAND_NAME`,
+ * which renames the PRODUCT: a wizard-configured organisation was never named, and an operator who set
+ * the brand to reach it got "This is Acme's Acme portal" with the title and the logo renamed too
+ * (measured on a published beta, 2026-09-11). The two differ on presence as well as on absence now.
  */
-export const ORGANISATION_NAME = process.env.CLEAROTRON_BRAND_NAME?.trim() || null;
+export const ORGANISATION_NAME = process.env.CLEAROTRON_ORGANISATION_NAME?.trim() || null;
 
 /**
  * THE CONFIDENTIALITY POSTURE ON A DELIVERED DOCUMENT — one rule, both report templates.

package/shared/invocation.mjs

@@ -36,8 +36,8 @@
 // below is not a resolver check: the shim is read and must NAME THIS INSTALL, and a `clearotron` found
 // earlier on PATH demotes the bare form rather than confirming it. Identity, not availability. A later
 // sweep tempted to simplify this into `command -v` would be reintroducing the defect, not tidying it.
-import { existsSync } from "node:fs";
-import { basename, sep } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, sep } from "node:path";
 import { INSTALL_DIR, inspectShim, pathPosition, shimDir, shimPath } from "./verb-shim.mjs";
 import { chdirPrefix } from "./os-advice.mjs";
 
@@ -272,6 +272,25 @@ export function invocationPrefix(argv1 = process.argv[1] ?? "", env = process.en
 export const invoke = (verb, argv1 = process.argv[1] ?? "", env = process.env, io = FS, installDir = INSTALL_DIR) =>
   `${invocationPrefix(argv1, env, io, installDir)}clearotron ${verb}`;
 
+/** This install's version when it runs from npx's cache, read off its own manifest; `null` anywhere else. */
+export function npxVersionOf(installDir = INSTALL_DIR, read = readFileSync) {
+  if (!/[\\/]_npx[\\/]/.test(String(installDir ?? ""))) return null;
+  try { return JSON.parse(read(join(installDir, "package.json"), "utf8")).version ?? null; } catch { return null; }
+}
+
+/**
+ * A command the reader can type from any directory that still runs after npm cleans its cache.
+ *
+ * `invoke` answers how this install is reached NOW. From npx's cache that is `cd <the cache> && npx
+ * clearotron …`, which stops working once npm cleans the cache, and a remedy is typed later, often after
+ * that. So from npx's cache this names the published version, `npx clearotron@<version> …`, which npm
+ * fetches again wherever it is typed. Everywhere else it is `invoke`'s answer.
+ */
+export function reachableCommand(verb, { argv1 = process.argv[1] ?? "", env = process.env, io = FS, installDir = INSTALL_DIR, read = readFileSync } = {}) {
+  const version = npxVersionOf(installDir, read);
+  return version ? `npx clearotron@${version} ${verb}` : invoke(verb, argv1, env, io, installDir);
+}
+
 /**
  * The verb by NAME ONLY — no prefix, no path, no `npx`.
  *
@@ -292,6 +311,16 @@ export const invoke = (verb, argv1 = process.argv[1] ?? "", env = process.env, i
  */
 export const bareInvocation = (verb) => `clearotron ${verb}`;
 
+/**
+ * A command for a page rendered in a browser: `bareInvocation`'s rule, never a path on this machine, with
+ * one exception. Run from npx's cache the bare name is one the reader does not have, so the published
+ * version is named instead, `npx clearotron@<version> …`, which runs anywhere and names no path.
+ */
+export const browserCommand = (verb, installDir = INSTALL_DIR, read = readFileSync) => {
+  const version = npxVersionOf(installDir, read);
+  return version ? `npx clearotron@${version} ${verb}` : bareInvocation(verb);
+};
+
 /**
  * Refuse a prompt when there is nobody to answer it.
  *

package/shared/permanent-install.mjs

@@ -161,7 +161,77 @@ export function packagedUpdate({ installDir = INSTALL_DIR, version = ownVersion(
  */
 export function stableInstallRoot({ installRoot = INSTALL_DIR, env = process.env, exists = existsSync } = {}) {
   if (!inNpxCache(installRoot)) return installRoot;
+  const has = (root) => !!root && exists(join(root, "mcp-server", "server.mjs"));
+  // A DEMO'S OWN COPY FIRST: it is this version, and it lives inside the demo's base. The demo's children
+  // are handed `CLEAROTRON_DEMO=1` and their workspace, `<base>/workspace`, which is how they find it.
+  const work = String(env?.CLEAROTRON_WORK_DIR ?? "").trim();
+  const demoRoot = env?.CLEAROTRON_DEMO === "1" && work ? packageRootUnder(demoProgramPrefix(dirname(work))) : null;
+  if (has(demoRoot)) return demoRoot;
   const prefix = permanentPrefix(env);
   const root = prefix ? packageRootUnder(prefix) : null;
-  return root && exists(join(root, "mcp-server", "server.mjs")) ? root : installRoot;
+  return has(root) ? root : installRoot;
+}
+
+/**
+ * WHERE A DEMO RUN FROM NPX KEEPS ITS OWN COPY OF THE PROGRAM: inside the demo's base, never `~/.local`.
+ *
+ * `npx clearotron demo` ran from npm's cache like `install` did, so the connect line it printed launched
+ * the connector from `_npx/<hash>/`, which npm deletes when it cleans up (measured on a published beta,
+ * 2026-09-11). The install's answer, a copy under `~/.local`, would leave a trace of the demo outside the
+ * demo's directory; this copy lives in `<base>/program`, so removing the demo is still one directory.
+ */
+export function demoProgramPrefix(base) {
+  return join(base, "program");
+}
+
+/**
+ * What `demo` does about its program. PURE given its inputs. `null` outside npx's cache; `{ skip }` on
+ * Windows, where npm's global layout differs, or with an unreadable version; otherwise a plan whose
+ * `current` says the copy is already this version, so a second start runs no npm at all.
+ */
+export function demoProgramPlan({ base, installDir = INSTALL_DIR, platform = process.platform, version = ownVersion(installDir), exists = existsSync, read = readFileSync } = {}) {
+  if (!inNpxCache(installDir)) return null;
+  if (platform === "win32") return { skip: "windows" };
+  if (!version) return { skip: "no-version" };
+  const prefix = demoProgramPrefix(base);
+  const root = packageRootUnder(prefix);
+  const current = exists(join(root, "mcp-server", "server.mjs")) && ownVersion(root, read) === version;
+  return {
+    prefix, root, version, current,
+    npmArgs: ["install", "--global", "--prefix", prefix, "--prefer-offline", "--no-fund", "--no-audit", `clearotron@${version}`],
+  };
+}
+
+/**
+ * Lays the demo's copy down when it is missing or another version, and returns its root; `null` when there
+ * is no copy to use (not run from npx, or a copy that could not be made). It never stops the demo: if npm
+ * fails, the demo runs from npx's cache as before and says what that costs. `demoProgramPlan` decides;
+ * this is the one place that acts on it, for `demo` and for a `start --demo` run from npx.
+ */
+export function ensureDemoProgram({ base, say, env = process.env, run = spawnSync, exists = existsSync, plan = demoProgramPlan({ base }) }) {
+  if (plan?.current) return plan.root;
+  if (!plan || plan.skip) return null;
+  say(`  program        copying clearotron ${plan.version} into ${plan.prefix}, so the commands below and your assistant's connection survive npm cleaning its cache`);
+  // The npm that launched this, when npm says which: no second npm is guessed at.
+  const npmCli = env.npm_execpath;
+  const opts = { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 };
+  const r = npmCli && exists(npmCli) ? run(process.execPath, [npmCli, ...plan.npmArgs], opts) : run("npm", plan.npmArgs, opts);
+  if (r.status === 0 && exists(join(plan.root, "mcp-server", "server.mjs"))) return plan.root;
+  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 commands and the connect line below run from npm's temporary`);
+  say("                 cache, so they stop working when npm cleans it; start the demo again to retry.");
+  return null;
+}
+
+/**
+ * The environment a demo's services get when they run from the demo's copy. What makes their printed
+ * commands name the copy is running from it: `invocationPrefix` answers from the running install. npm's
+ * marks of an npx arrival (`npm_command=exec` among them) and the npx path the dispatcher hands down
+ * describe a process npm started, which the copy is not, so they are taken off, as `install` takes them
+ * off when it moves out of the cache.
+ */
+export function demoProgramEnv(env = process.env) {
+  const out = { ...env };
+  for (const k of ["npm_command", "npm_lifecycle_event", "npm_execpath", "CLEAROTRON_INVOKED_AS"]) delete out[k];
+  return out;
 }