clearotron 0.3.0-beta.7 → 0.3.0-beta.8

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,7 +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 { demoProgramPlan } from "../shared/permanent-install.mjs";   // — a demo from npx keeps its own copy
+import { ensureDemoProgram } from "../shared/permanent-install.mjs";   // — a demo from npx keeps its own copy
 import { mergeEnvFile } from "../shared/env-file-merge.mjs";
 import { mcpOriginFor } from "../shared/lane-address.mjs";   // — one author for the origin
 import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "../shared/server-units.mjs";   // — one authority, two callers
@@ -123,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";
@@ -1253,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)
@@ -1464,25 +1464,9 @@ if (isMain) {
   // The same version goes into `<base>/program` (shared/permanent-install.mjs), BEFORE the services start
   // so the portal's connect rows name it too, and only when it is not there already. It never stops the
   // demo: if npm fails, the demo runs as before and says the line will not survive a cache clean.
-  let demoProgramRoot = null;
-  if (DEMO) {
-    const plan = demoProgramPlan({ base: paths.base });
-    if (plan?.current) demoProgramRoot = plan.root;
-    else if (plan && !plan.skip) {
-      say(`  program        copying clearotron ${plan.version} into ${plan.prefix}, so your assistant's connection survives npm cleaning its cache`);
-      // The npm that launched this, when npm says which: no second npm is guessed at.
-      const npmCli = process.env.npm_execpath;
-      const r = npmCli && existsSync(npmCli)
-        ? spawnSync(process.execPath, [npmCli, ...plan.npmArgs], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 })
-        : spawnSync("npm", plan.npmArgs, { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 180_000 });
-      if (r.status === 0 && existsSync(join(plan.root, "mcp-server", "server.mjs"))) demoProgramRoot = plan.root;
-      else {
-        const why = r.error ? r.error.message : String(r.stderr ?? "").trim().split("\n").pop() || `npm exited ${r.status}`;
-        say(`  program        could not be copied (${why}). The connect line below runs from npm's temporary cache,`);
-        say("                 so it stops working when npm cleans that cache; start the demo again to retry.");
-      }
-    }
-  }
+  // `clearotron demo` makes the copy before it starts this file, and starts this file FROM the copy, so
+  // there this finds nothing to do; it acts for a `start --demo` typed at npx directly.
+  const demoProgramRoot = DEMO ? ensureDemoProgram({ base: paths.base, say }) : null;
 
   const envs = childEnv({ ports, paths, user, portalSecret, tokenSecret, opsToken,
     localWorker: wantWorker, demo: DEMO, clientFence: declaredFence || null,

package/build-info.json

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

package/driver/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.7",
+  "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": 11,
-          "asserts": 61,
-          "skips": 6,
+          "tests": 13,
+          "asserts": 78,
+          "skips": 7,
           "todos": 0
         },
         "an-mcp-route-says-which-challenge-it-answers-with.test.mjs": {
@@ -2747,7 +2747,7 @@
         },
         "no-internal-hostname-ships-in-the-package.test.mjs": {
           "tests": 1,
-          "asserts": 3,
+          "asserts": 4,
           "skips": 0,
           "todos": 0
         },
@@ -3095,7 +3095,7 @@
         },
         "portal-service.test.mjs": {
           "tests": 124,
-          "asserts": 670,
+          "asserts": 671,
           "skips": 1,
           "todos": 0
         },
@@ -4587,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,9 @@
 # trademark-artifacts-mcp
 
+## 0.3.0-beta.8
+
+No changes in this release.
+
 ## 0.3.0-beta.7
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.7",
+  "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.7",
+  "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.7",
+  "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,9 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.0-beta.8
+
+No changes in this release.
+
 ## 0.3.0-beta.7
 
 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.7",
+  "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/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

@@ -201,3 +201,37 @@ export function demoProgramPlan({ base, installDir = INSTALL_DIR, platform = pro
     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;
+}