clearotron 0.3.2-beta.10 → 0.3.2-beta.11

package/CONTRIBUTING.md

@@ -17,6 +17,7 @@ runs on `node:sqlite`. Node 20 will fail in ways that look like your change.
 
 ```bash
 npm install
+npm run build:ui            # the browser bundle is not committed; the demo needs it
 npm test                    # the fast tier, offline, no network, no keys
 ```
 

package/INSTALL.md

@@ -16,7 +16,7 @@ after §5 is needed to produce a report.
 | | Sections | For |
 |---|---|---|
 | **Installing** | §1 Prerequisites · §2 Install · §3 Configuration · §3a Free register route · §3b Paying through a cloud account · §4 Config store · §5 Run a clearance | Anyone |
-| **Operating** | §6 `npx clearotron start` · §7 The MCP server · §8 Access control and isolation | Running it as a service for other people |
+| **Operating** | §6 Start the product · §7 The MCP server · §8 Access control and isolation | Running it as a service for other people |
 | **Reference** | §9 What an integrator supplies · §10 Licence | — |
 
 Before §3, decide which register you are using — it is the first real choice and the fastest route is
@@ -113,7 +113,7 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
   pay for Claude through your own Google Cloud, Microsoft Azure or Amazon Bedrock account (§3b).
 
   **Installed is not usable.** `npx clearotron install` proves the engine can complete a turn before it
-  writes anything, and `npx clearotron doctor --probe-engine` re-proves it on a configured box. Both
+  writes anything, and `clearotron doctor --probe-engine` re-proves it on a configured box. Both
   spend one cheap turn; plain `doctor` spends nothing.
 - **A register credential**, and **`PERPLEXITY_API_KEY`**. Both are required for a real run and both
   fail closed at preflight — before a stage has spent, never at the grid after. The one exception is a
@@ -202,8 +202,8 @@ tarball as a dependency.** Not an unpacked archive; there is no step here that u
 mkdir ~/app && cd ~/app
 npm init -y
 npm install /path/to/clearotron-<version>.tgz
-npx clearotron doctor          # reads; writes nothing, calls nobody
 npx clearotron install         # the wizard
+clearotron doctor              # reads; writes nothing, calls nobody
 ```
 
 `npx` works from `~/app` because npm links a **dependency's** `bin` into the consuming project — the
@@ -264,7 +264,10 @@ there. On the repository route "the project" is the checkout; on the packaged ro
 you ran `npm init` in — and on that route `clearotron` IS a dependency, so `npx` finds it in
 `node_modules/.bin` exactly as the paragraph above describes.
 
-**`clearotron install` (§3) puts the short form on your `PATH`** and you can stop typing `npx` after it:
+**`clearotron install` (§3) puts the short form on your `PATH`**, and every command after it in this
+document uses that form. Use it rather than a fresh `npx clearotron`: `npx` resolves whichever version npm
+picks at that moment — the stable, unless you name a channel — and does not hand over to the copy the
+install placed. You can stop typing `npx` after it:
 it writes a small shim to `~/.local/bin/clearotron` pointing at this checkout. That directory needs no
 root — `npm link` would want npm's global prefix, which on a default install is `/usr` and refuses
 without it. Most login profiles add `~/.local/bin` to `PATH` only if it already existed when the shell
@@ -413,7 +416,7 @@ If you would rather not write this file by hand, `npx clearotron install` asks f
 these paths under it, checks what it can check without billing you before it writes anything, and never
 touches a path you did not name — an engine turn, an EUIPO token exchange, and an offered (not assumed)
 Perplexity ping. A paid register key is deliberately not probed: a call against a metered subscription is
-a charge you did not ask for, so that credential is written on your word. `npx clearotron doctor`
+a charge you did not ask for, so that credential is written on your word. `clearotron doctor`
 reports what is set and what is missing, and writes nothing.
 
 Only the integrator-set knobs are shown — copy what you need:
@@ -597,9 +600,9 @@ points on it.
 | What it is | What the product calls it | Where it lives | What creates it |
 |---|---|---|---|
 | A group of people and the companies they clear for — a firm, a brand team, one company on a hosted install | **organisation** (`tenant` in `grants.json`) | a key under `tenants` in `grants.json`, with its `name` | setup creates the first; after that, a key you add to `grants.json` |
-| A company you do clearances for | **company** (`account` in `grants.json` and on the wire; the CLI calls it **brand owner**) | a bundle in the company store, keyed by an account key, and listed under exactly one organisation | the portal's `+ New company`, or `npx clearotron brandowner add <key>` |
-| One engagement under that company — its classes, jurisdictions, platforms | **project** | inside that company's bundle | `npx clearotron project add` |
-| Someone who may see some of it | **person** | `grants.json`: their access under each organisation's `users`, their two switches under `people` | the portal's People page, or `npx clearotron grant add` |
+| A company you do clearances for | **company** (`account` in `grants.json` and on the wire; the CLI calls it **brand owner**) | a bundle in the company store, keyed by an account key, and listed under exactly one organisation | the portal's `+ New company`, or `clearotron brandowner add <key>` |
+| One engagement under that company — its classes, jurisdictions, platforms | **project** | inside that company's bundle | `clearotron project add` |
+| Someone who may see some of it | **person** | `grants.json`: their access under each organisation's `users`, their two switches under `people` | the portal's People page, or `clearotron grant add` |
 
 Nesting, in one line: **an organisation contains companies; a company contains projects; a person is
 given access to points on that tree — the whole install, an organisation, or one company — and sees
@@ -613,7 +616,7 @@ Three consequences worth stating, because each has surprised someone:
   stops them; **Manage** adds people, adds companies and changes settings. Viewing is not a permission:
   access is viewing. A person with no entry under `people` sees what their access covers and starts
   nothing.
-- **A key grants no reach of its own.** `npx clearotron key issue` mints the identity a person's assistant
+- **A key grants no reach of its own.** `clearotron key issue` mints the identity a person's assistant
   presents; what that identity may see and do is decided by the guest list at the moment of each call.
   Enrol first, issue second — a key for someone with no access reaches nothing, and is not an error
   anywhere.
@@ -710,7 +713,7 @@ Copy or author the companies, context packs and project overlays you want; assum
 ## 5. Run a headless clearance report
 
 1. Make sure `CLEAROTRON_AI` names the engine you want (`anthropic-agent` or `openai-agent`), its CLI is
-   authenticated, and your active register provider's credential is set. `npx clearotron doctor
+   authenticated, and your active register provider's credential is set. `clearotron doctor
    --probe-engine` answers all three, and the engine half of it by actually running a turn — an
    executable on `PATH` that is signed out passes every other check and fails at the first stage.
 
@@ -760,7 +763,7 @@ Copy or author the companies, context packs and project overlays you want; assum
 3. Run the pipeline:
 
    ```
-   npx clearotron run --job job.json
+   clearotron run --job job.json
    ```
 
    **The example above is sized in minutes; a real clearance is sized in hours.**
@@ -834,7 +837,7 @@ A run stopped by a **provider rate limit** or parked for **automatic recovery**
 that is the systemd units in `driver/systemd/`. Everywhere else, run the watcher yourself:
 
 ```
-npx clearotron run-queue --watch
+clearotron run-queue --watch
 ```
 
 That polls every 90 seconds for queued jobs and for parked runs whose window has elapsed, and it resumes
@@ -847,18 +850,18 @@ stops it, and anything still parked waits for the next time you start it.
 Everything above runs the engine from a job file. This is the product: a portal you sign in to, order a
 clearance from, and read the report in.
 
-**Plain `npx clearotron start` runs in the foreground and stops when this terminal closes** — Ctrl-C, a
+**Plain `clearotron start` runs in the foreground and stops when this terminal closes** — Ctrl-C, a
 dropped SSH session, a shut laptop lid ending the session: the portal goes with it. That is the right
 shape for trying things. To keep it running when the window is gone:
 
 ```
-npx clearotron start --background     # the same product, as user services that survive the terminal
-npx clearotron status                 # is it up, and on which ports
-npx clearotron stop                   # stop it and give the box back — plain `start` works again
+clearotron start --background     # the same product, as user services that survive the terminal
+clearotron status                 # is it up, and on which ports
+clearotron stop                   # stop it and give the box back — plain `start` works again
 ```
 
-`--background` never touches the assistant connector: `npx clearotron connect` opens that door
-and `npx clearotron disconnect` closes it, separately and on purpose.
+`--background` never touches the assistant connector: `clearotron connect` opens that door
+and `clearotron disconnect` closes it, separately and on purpose.
 
 **If anything else on this host already runs this product, set its ports first.** The portal (18802)
 and the engine door (18790) are **fixed defaults shared by every checkout on a machine**, so a second
@@ -866,14 +869,14 @@ instance collides with the first and `start` refuses rather than quietly moving.
 before the first start:
 
 ```
-PORTAL_SERVICE_PORT=18820 TRADEMARK_MCP_HTTP_PORT=18821 npx clearotron start
+PORTAL_SERVICE_PORT=18820 TRADEMARK_MCP_HTTP_PORT=18821 clearotron start
 ```
 
 A test instance beside a live one needs more than two ports — §8, *Two instances on one machine*, is the
 whole boundary. On a host running nothing else, ignore this and carry on:
 
 ```
-npx clearotron start
+clearotron start
 ```
 
 One command. It starts the portal and the engine door the portal's Start button calls, waits until both
@@ -881,14 +884,14 @@ answer, and prints one address to open. `Ctrl-C` stops both. The second run asks
 
 **This is not `npx clearotron demo`, and the two are not interchangeable.**
 
-| | `npx clearotron demo` | `npx clearotron start` |
+| | `npx clearotron demo` | `clearotron start` |
 |---|---|---|
 | what it is | a finished report, replayed | the running product |
 | credentials | none | whatever a real run needs (§3) |
 | model calls | none | yes, once you order a clearance |
 | what you can do | read | sign in, configure, order, read |
 
-Use the demo to see what this system produces. Use `npx clearotron start` to run it.
+Use the demo to see what this system produces. Use `clearotron start` to run it.
 
 ### What the first start does, once
 
@@ -898,7 +901,7 @@ Use the demo to see what this system produces. Use `npx clearotron start` to run
   `clearotron doctor` and a connected assistant read the same saved searches as the portal.
 - Creates `~/trademark/` — `pool/`, `workspace/`, `queue/`, `outbox/`, `locks/`, an empty grants file,
   and a small git repository for saved searches. Same base directory `npx clearotron install` uses, so whichever
-  of the two you ran first, the other finds the same install. Move it with `npx clearotron start --base <dir>`.
+  of the two you ran first, the other finds the same install. Move it with `clearotron start --base <dir>`.
   That does not move anything the env file already names: the saved-search lines above, and the data
   directories `npx clearotron install` wrote, keep pointing at the old place until you edit them.
 - Mints your sign-in passphrase and **prints it once**. Write it down. It is stored as a scrypt digest in
@@ -911,7 +914,7 @@ Use the demo to see what this system produces. Use `npx clearotron start` to run
 You sign in as `<your-username>@localhost` unless you say otherwise:
 
 ```
-npx clearotron start --user you@example.com
+clearotron start --user you@example.com
 ```
 
 Setup does not ask for the address: it writes the local-account form to `.env` and shows it once, in
@@ -923,7 +926,7 @@ nobody else at its domain; enrolling anyone else is that same file, exactly as o
 
 **No authentication is switched off to make this work, and none can be.** Both doors prove who the
 caller is — the portal by passphrase and a signed session cookie, the engine door by a mandatory
-access key that `npx clearotron start` mints in memory at every start and never writes down. The key is scoped to
+access key that `clearotron start` mints in memory at every start and never writes down. The key is scoped to
 two verbs and capped to the companies this install knows about. The `*_AUTH_DISABLED` switches
 elsewhere in this repository are for something else and are written into the child environment as `0`.
 
@@ -941,7 +944,7 @@ no proxy in front is the one shape to avoid — the portal refuses to start with
 
 ### It drains its own queue
 
-`npx clearotron start` supervises a worker alongside the portal, so ordering a clearance from the portal
+`clearotron start` supervises a worker alongside the portal, so ordering a clearance from the portal
 runs it.
 
 The consent did not move and did not weaken. The portal prices the run, quotes how long it takes, and
@@ -953,8 +956,8 @@ If you want the old separation — order here, drain deliberately over there —
 run the queue yourself:
 
 ```
-npx clearotron start --no-worker
-npx clearotron run-queue --watch
+clearotron start --no-worker
+clearotron run-queue --watch
 ```
 
 A queued job whose worker is not running says so on the portal rather than sitting at "Waiting to start".
@@ -982,7 +985,7 @@ systemctl --user daemon-reload && systemctl --user enable --now clearotron-deplo
 
 A busy box simply skips: the service exits clean when a run is live and the next firing tries again.
 
-**`npx clearotron doctor` reports how far behind this install is**, beside everything else it checks. It
+**`clearotron doctor` reports how far behind this install is**, beside everything else it checks. It
 does not fetch, so the count is against your last fetch — which it says. An install that is not a git
 checkout, or a branch with no upstream, says that instead of reporting a number it cannot compute.
 
@@ -997,7 +1000,7 @@ yours to do, and now yours to know about.
 
 The portal is on 18802 and the engine door on 18790, both loopback, and both are **fixed defaults for
 every checkout on the host** rather than per-install values. They move separately: the portal with
-`npx clearotron start --port <n>` or `PORTAL_SERVICE_PORT=<n>`, the engine door with
+`clearotron start --port <n>` or `PORTAL_SERVICE_PORT=<n>`, the engine door with
 `TRADEMARK_MCP_HTTP_PORT=<n>`. A port already in use produces a sentence saying which port and which
 variable to change, before anything starts — it will not quietly pick another, because whatever sits in
 front of it is still addressed to the old one.
@@ -1073,17 +1076,17 @@ their own integration work.
 
 1. **Clearotron is installed on the machine the assistant runs on** — Claude's desktop app, Claude Code,
    Codex, the ChatGPT desktop app, an agent that runs commands. The assistant spawns the server over
-   stdio. No address, no key, no network, no ingress. `npx clearotron start` prints the one line to
-   paste, and `npx clearotron connect --where here` hands it over per assistant.
+   stdio. No address, no key, no network, no ingress. `clearotron start` prints the one line to
+   paste, and `clearotron connect --where here` hands it over per assistant.
 2. **Clearotron is running somewhere else** — a server, a cloud machine, anywhere the assistant is
    not. These need **a publicly reachable HTTPS address**, plus a key made for the person connecting.
    Always. Claude (app, web, Cowork and mobile), ChatGPT on the web, Perplexity and other agents only
-   ever connect this way; Claude Code and Codex can connect either way. `npx clearotron connect
+   ever connect this way; Claude Code and Codex can connect either way. `clearotron connect
    --where elsewhere` makes the key and prints the steps for the assistant you name.
 
 Without `--where`, `connect` asks when both answers are possible, and `--client <name>` on its own keeps
 the answer that assistant had before: a key for Claude, the local line for Claude Code and Codex.
-`npx clearotron disconnect` takes the same `--where`.
+`clearotron disconnect` takes the same `--where`.
 
 **A loopback address is never an answer for shape 2, and that is not about your network.** A remote MCP
 connector is reached **from the vendor's cloud**, never from the reader's device. Anthropic's own help
@@ -1091,7 +1094,7 @@ centre states it: *"Claude connects to your remote MCP server from Anthropic's c
 rather than from your local device. This is true across every Claude client, including claude.ai, Claude
 Desktop, Cowork, and the mobile apps … Your MCP server must be reachable over the public internet."*
 So an install behind `ssh -L` or an editor's port forward serves shape 1 perfectly and cannot serve
-shape 2 at all, however the reader reaches the portal. `npx clearotron connect` says so plainly rather
+shape 2 at all, however the reader reaches the portal. `clearotron connect` says so plainly rather
 than printing an address that will be rejected.
 
 **The address is set once, at install.** `npx clearotron install` asks for it — *"the address companies'
@@ -1100,7 +1103,7 @@ Use-your-AI page, a report's Ask-your-AI control and `doctor` all read. Leave it
 install: every one of those surfaces then shows its honest empty state, which is correct for a machine
 with no public address. Changing it later is editing that one setting and restarting.
 
-Whatever you provision, `npx clearotron doctor` will tell you whether the published address actually
+Whatever you provision, `clearotron doctor` will tell you whether the published address actually
 answers — being set is not the same as being reachable, and the page and the report both render from
 the value being present alone. An address that does not answer is reported as a problem with the
 reason, never as configured.
@@ -1168,7 +1171,7 @@ curl -sS -o /dev/null -w '%{http_code}\n' https://<your-host>/mcp
 
 Anything that comes back — including a 401 or a 405 — proves the route reaches the connector; a
 connection error or a login page does not. Put the address that answered into the installer's question
-(or `CLEAROTRON_CLIENT_MCP_URL`), then `npx clearotron doctor` and read the connector line.
+(or `CLEAROTRON_CLIENT_MCP_URL`), then `clearotron doctor` and read the connector line.
 
 Smoke-test either face offline:
 
@@ -1191,28 +1194,28 @@ bills Claude through an API key or a cloud account, never a Claude subscription,
 require.
 
 **The guest list.** `CLEAROTRON_ACCESS_FILE` turns account scoping on for **every face at once** — the
-portal, the MCP read face, and the client connector. `npx clearotron start` (§6) writes one into its
+portal, the MCP read face, and the client connector. `clearotron start` (§6) writes one into its
 state directory the first time it runs: you, with access to everything, your organisation if setup was
 told its name, and nobody else yet.
 [examples/grants.example.json](examples/grants.example.json) is a runnable guest list over the demo
 companies.
 
-**Giving someone access.** `npx clearotron grant add` writes the same file the portal's People page
+**Giving someone access.** `clearotron grant add` writes the same file the portal's People page
 writes:
 
 ```
-npx clearotron grant add <email> --tenant <organisation> --accounts <key,key|*> [--run] [--manage]
+clearotron grant add <email> --tenant <organisation> --accounts <key,key|*> [--run] [--manage]
 ```
 
 `--accounts '*'` is the whole organisation, including companies filed under it later. `--run` lets the
 person start and stop clearances; `--manage` lets them add people and companies and change settings.
 With neither, they can see what their access covers and start nothing.
 
-**Keys for people.** `npx clearotron grant` enrols someone; it decides what they may see and issues
+**Keys for people.** `clearotron grant` enrols someone; it decides what they may see and issues
 nothing. The key their assistant actually presents comes from a different verb:
 
 ```
-npx clearotron key issue <email> [--accounts a,b] [--ttl-days 90]
+clearotron key issue <email> [--accounts a,b] [--ttl-days 90]
 ```
 
 It is printed once, on stdout, and stored nowhere — possession is the credential. Enrol first: the key
@@ -1227,7 +1230,7 @@ node mcp-server/mint-token.mjs --scope ops --sub <name> --ttl-days 30 --verbs st
 ```
 
 Said plainly rather than dressed as a verb, because the distinction costs real time: **`npx clearotron
-key issue` mints ACCOUNT keys only**, and `npx clearotron grant` mints nothing at all. This page
+key issue` mints ACCOUNT keys only**, and `clearotron grant` mints nothing at all. This page
 previously sent readers to `grant` for an ops token, which is why the sentence is now this long.
 
 **When you have to re-mint one.** Not on the ordinary path any more, and this paragraph used to say
@@ -1307,7 +1310,7 @@ https://claude.com/api/mcp/auth_callback
 https://chatgpt.com/connector_platform_oauth_redirect
 ```
 
-`npx clearotron doctor --probe-connector` asks your own door whether each of those can register, with a
+`clearotron doctor --probe-connector` asks your own door whether each of those can register, with a
 localhost control first so a broken endpoint is never reported as a policy refusal. It is opt-in because
 each successful attempt creates a throwaway OAuth client on your account — every other `doctor` check
 writes nothing.
@@ -1318,7 +1321,7 @@ writes nothing.
 > whether the application was recreated before you change anything else.
 
 **Seeing what a company sees.** There is no "view as" screen. The documented route is a **client-scoped
-connector key**: issue one for that company with `npx clearotron key issue`, point an assistant at the
+connector key**: issue one for that company with `clearotron key issue`, point an assistant at the
 client connector with it, and you get exactly that company's scope. Changing `PORTAL_LOCAL_USER` to
 impersonate someone is not the answer — local sign-in is one user by design, and the service refuses to
 start if the credential does not match the configured address, so you lose your own access and take the
@@ -1391,7 +1394,7 @@ the orchestrator, the provider adapters and the documentation.
 
 AGPL §13 matters if you run it as a network service: anyone who interacts with your instance is owed
 the source of **that** instance. Every network face answers with its own running commit — the portal's
-About page, the MCP server's `server_info`, and `npx clearotron start --license`.
+About page, the MCP server's `server_info`, and `clearotron start --license`.
 
 **Everything §1 told you to bring is outside it.** Read this before you count the licence as your
 answer on any of them:

package/README.md

@@ -43,8 +43,9 @@ npx clearotron install
 
 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
+before it saves it. Every command below uses the `clearotron` it installed — the same channel you
+installed from — so if `~/.local/bin` is not on your `PATH` yet, type the full path,
+`~/.local/bin/clearotron`, instead. **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 spawns each stage with POSIX path and process semantics, so
 a clearance is refused there before it starts.
@@ -71,13 +72,13 @@ With it installed, check what it found before it does anything. `doctor` only re
 calls nobody, and names whatever is still missing:
 
 ```bash
-npx clearotron doctor
+clearotron doctor
 ```
 
 Then start the product and open the portal address it prints:
 
 ```bash
-npx clearotron start
+clearotron start
 ```
 
 That is the portal everyone at your company uses. Ordering a clearance is the same screen — describe it
@@ -99,7 +100,7 @@ rights-holders behind them by jurisdiction:
 Then run your own: order it in the portal, or hand the engine a job file:
 
 ```bash
-npx clearotron run --job my-job.json
+clearotron run --job my-job.json
 ```
 
 ## How it fits together
@@ -158,8 +159,8 @@ npx clearotron demo            # replays finished clearances into a local portal
 
 From a clone the commands are `npx clearotron …`, run from that directory.
 
-`npm test` is the whole verification story for someone with no credentials, and it is the first thing
-[CONTRIBUTING.md](CONTRIBUTING.md) asks of a contributor.
+`npm test` is the offline suite and the first thing [CONTRIBUTING.md](CONTRIBUTING.md) asks of a
+contributor; `npm run test:full`, also free, is the merge gate.
 
 ## Project documents
 

package/bin/onboard.mjs

@@ -1030,6 +1030,31 @@ export function installSizeLine(eng) {
   return `${Number.isFinite(eng?.installMB) ? `It takes about ${eng.installMB} MB. ` : ""}To remove it, delete that folder.`;
 }
 
+/**
+ * Whether a login shell will put `dir` on the PATH: some profile this user's shells read names it.
+ *
+ * Setup promised "open a new login shell, and plain `clearotron start` works". That is Ubuntu's stock
+ * `~/.profile` for an ordinary user, which adds `~/.local/bin` once it exists. It is not root's in a fresh
+ * container, measured on ubuntu:24.04 by an outside install, and it is not macOS's default zsh. So the
+ * promise is made only when a profile names the directory. A profile that adds it some other way reads as
+ * "no", which costs a reader one line of advice and never sends them to a shell that will not find it.
+ */
+const LOGIN_PROFILES = [".profile", ".bash_profile", ".bash_login", ".bashrc", ".zprofile", ".zshenv", ".zshrc", ".zlogin"];
+export function aLoginShellAdds(dir, { home = homedir(), read = (p) => readFileSync(p, "utf8") } = {}) {
+  const d = String(dir ?? "");
+  if (!d) return false;
+  const rel = home && d.startsWith(`${home}/`) ? d.slice(home.length + 1) : null;
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = new RegExp(`(^|[^\\w.-])(${esc(d)}${rel ? `|(\\$HOME|\\$\\{HOME\\}|~)/${esc(rel)}` : ""})(?![\\w.-])`);
+  for (const f of LOGIN_PROFILES) {
+    let text;
+    try { text = read(join(home, f)); } catch { continue; }
+    // A COMMENTED-OUT LINE ADDS NOTHING, and a disabled PATH line is an ordinary state for a profile.
+    if (String(text ?? "").split("\n").some((l) => !/^\s*#/.test(l) && names.test(l))) return true;
+  }
+  return false;
+}
+
 /**
  * The engine menu, built from the driver's registry so the wizard cannot offer an adapter that does not
  * exist — or hide one that does. Same guarantee the register-provider list has.
@@ -1997,7 +2022,7 @@ export async function runCheck() {
       info(`this install's own is ${form.shim} — the commands below name it in full, so they reach THIS install`);
     } else if (form.form === "shim-path") {
       warn(`${form.dir} is not on this shell's PATH, so the bare \`clearotron\` will not resolve here`);
-      info(`add it with: export PATH="${form.dir}:$PATH"  — or open a new login shell`);
+      info(`add it with: export PATH="${form.dir}:$PATH"${aLoginShellAdds(form.dir) ? "  — or open a new login shell" : ""}`);
     } else if (form.form === "npx-pinned") {
       info(`this is running from npm's npx cache, so the commands below name this version through npx (\`${form.prefix.trim()}\`), `
         + `which works from any directory and after npm cleans its cache; \`${invoke("install")}\` puts \`clearotron\` on your PATH`);
@@ -4029,20 +4054,25 @@ try {
   say("\n  Register provider");
   say("  This decides which register gets searched, and which vendor gets billed. There is no default in");
   say("  the engine — it refuses to guess.");
-  const provider = await choose("Which register?", PROVIDERS.map((p) => ({ label: `${p.label} — ${p.cost}`, spec: p })), 0);
+  // THE LAST ROW IS NOT A REGISTER, as on the AI question, and with the same words. Leaving the register
+  // unset was reachable only by picking a vendor and skipping its credential, so a reader who meant "none
+  // yet" had to pretend to choose one. Choosing it takes the branch a skipped credential reaches below.
+  const provider = await choose("Which register?", [...PROVIDERS.map((p) => ({ label: `${p.label} — ${p.cost}`, spec: p })), { label: "None for now", spec: null }], 0);
   const spec = provider.spec;
-  say(`\n  ${spec.label}: covers ${spec.covers}`);
-  for (const w of spec.warnings ?? []) warn(w);
-  if (spec.signup && !spec.credentials.every((k) => present(candidate[k]))) {
-    say("\n  How to get a credential:");
-    for (const l of spec.signup) say(`    ${l}`);
-    say("");
+  if (spec) {
+    say(`\n  ${spec.label}: covers ${spec.covers}`);
+    for (const w of spec.warnings ?? []) warn(w);
+    if (spec.signup && !spec.credentials.every((k) => present(candidate[k]))) {
+      say("\n  How to get a credential:");
+      for (const l of spec.signup) say(`    ${l}`);
+      say("");
+    }
   }
   // ── — INSTALL MAY FINISH WITH NO REGISTER. Ruling, 2026-08-26 ──────────────────────
   //
   // Every row of PROVIDERS declares required credentials, and this prompt had no way out, so a reader
-  // with no vendor account could not reach the closing screen at all — the menu offers no "none" row,
-  // which means they arrive here without ever having chosen to supply a key.
+  // with no vendor account could not reach the closing screen at all. The menu's "None for now" row is
+  // the chosen way here; a skipped credential is the other.
   //
   // A REGISTER IS ALL-OR-NOTHING, WHICH IS WHY ONE SKIP ABANDONS THE WHOLE SELECTION. Half a credential
   // pair is not a working register; writing CLEAROTRON_DATABASE beside it would name an adapter that
@@ -4053,14 +4083,14 @@ try {
   // is single-valued with no default, a run already refuses by name when it is unset
   // (driver.config.mjs), and the Installation settings page already says a register is needed.
   // One register per install, any one of them sufficient, none a precondition for another.
-  let registerSelected = true;
+  let registerSelected = spec != null;
   // What THIS step collected, so abandoning the selection can take it back. Measured: a register with
   // two required credentials — `euipo`, `free-tier` — let a reader supply the first and skip the second,
   // and the first was written to the .env with no CLEAROTRON_DATABASE beside it. `candidate` is
   // serialised wholesale at the write step, so anything left in it ships. A credential for a register
   // nobody selected is a secret persisted for a decision that was reversed.
   const collectedHere = [];
-  for (const k of spec.credentials) {
+  for (const k of spec?.credentials ?? []) {
     if (present(candidate[k])) { ok(`${k} already adopted from your environment`); continue; }
     const v = await askValue(`${k}:`, { secret: true, skippable: true,
       skipped: `${k} not set, so ${spec.id} cannot be configured — this install will have NO register selected.` });
@@ -4581,7 +4611,8 @@ try {
     say(`  \`clearotron\` is now installed at ${form.shim}, and ${form.dir} is not on this shell's`);
     say("  PATH yet — most login profiles add it only if it existed when the shell started. So:\n");
     say(`    export PATH="${form.dir}:$PATH"     # this terminal, now`);
-    say("      …or open a new login shell, and plain `clearotron start` works from anywhere.\n");
+    if (aLoginShellAdds(form.dir)) say("      …or open a new login shell, and plain `clearotron start` works from anywhere.\n");
+    else say("");
   } else if (form.form === "in-place") {
     say("  There is no `clearotron` on your PATH, so the commands above name the directory to run them");
     say("  from. Re-run the install to put the verb on your PATH.\n");

package/bin/start.mjs

@@ -2322,7 +2322,7 @@ if (isMain) {
   // Captured HERE, immediately before the spawn, rather than beside the sentence that reads it: the
   // check has to sit on the other side of the thing that mints, and the only way to keep that true is
   // for it to be adjacent to the spawn where a reader can see why.
-  const { credentialPathFor: credentialPathBeforeStart, newPassphrase, passphraseResetCommand, demoCredentialToReplace, laterStartLines, readLocalCredential } = await import("../driver/portal-local-auth.mjs");
+  const { credentialPathFor: credentialPathBeforeStart, newPassphrase, passphraseResetCommand, passphraseWithheldLines, demoCredentialToReplace, laterStartLines, readLocalCredential } = await import("../driver/portal-local-auth.mjs");
   // ASKED ABOUT THE FILE THE PORTAL WILL ACTUALLY USE, not the shared default. `credentialPathFor`
   // reads `PORTAL_LOCAL_CREDENTIAL`, and a demo sets it to a file inside its own base — but this call
   // was made against THIS process's environment, which never carries it. So on any box that already had
@@ -2486,16 +2486,25 @@ if (isMain) {
   // line is what a reader copies when they lose the passphrase — run as printed, the bare form resolved
   // the shared default and exited 1 saying no credential exists.
   const reset = passphraseResetCommand({ prefix: invocationPrefix(), credentialPath: envs.portal.PORTAL_LOCAL_CREDENTIAL ?? null });
+  // ── ONLY A TERMINAL IS HANDED THE PASSPHRASE ──────────────────────────────────────────────────────
+  //
+  // The first-start box went to standard output whatever standard output was. Under a service manager,
+  // `nohup` or `> start.log` that is a file, so the one value this product cannot read back landed in a
+  // log, a moment after the portal's own line said it was being withheld for exactly that reason.
+  // Measured on a published beta by an outside install. A redirected run gets the portal's own words
+  // instead, from the composer the portal uses, and the way to mint one on a terminal.
   if (mintedPassphrase) {
     const rule = "─".repeat(66);
     say(`  ┌${rule}┐`);
     say(`  │  Open        ${envs.url}`);
     say(`  │  Sign in as  ${user}`);
-    say(`  │  Passphrase  ${mintedPassphrase}`);
-    say(`  │`);
-    say(`  │  WRITE THE PASSPHRASE DOWN NOW. It is stored only as a digest, so`);
-    say(`  │  nothing — not this product, not this terminal — can read it back.`);
-    say(`  │  Lost it? ${reset}`);
+    if (process.stdout.isTTY === true) {
+      say(`  │  Passphrase  ${mintedPassphrase}`);
+      say(`  │`);
+      say(`  │  WRITE THE PASSPHRASE DOWN NOW. It is stored only as a digest, so`);
+      say(`  │  nothing — not this product, not this terminal — can read it back.`);
+      say(`  │  Lost it? ${reset}`);
+    } else for (const line of passphraseWithheldLines({ stream: "stdout", resetCommand: reset }).flatMap((l) => (/^\s/.test(l) ? [l] : fitTo(64, l)))) say(`  │  ${line}`);
     // THE HINT BELONGS IN THE BOX TOO, and this was the reader the whole sentence was written for. The
     // frame exists because a first-time reader skips the log wall and acts on it — so the one address
     // they copy was the one address with nothing beside it saying what to do when the page that opens
@@ -2604,6 +2613,22 @@ export function demoBaseIsTheReaders({ baseGiven = false, ownBase = false, base
   return !(ownBase && base && demoDefault && base === demoDefault);      // handed over, and it IS the default
 }
 
+/**
+ * A sentence broken at spaces into lines of at most `width` characters, for the framed box. The withheld
+ * lines come from the portal's composer, written for a log line of any length; inside the frame they are
+ * broken to the width of the lines they stand in for. A word longer than `width` keeps its own line. PURE.
+ */
+export function fitTo(width, text) {
+  const out = [];
+  let line = "";
+  for (const word of String(text ?? "").split(/\s+/).filter(Boolean)) {
+    if (line && line.length + 1 + word.length > width) { out.push(line); line = word; }
+    else line = line ? `${line} ${word}` : word;
+  }
+  if (line) out.push(line);
+  return out;
+}
+
 export function demoBaseResetTarget({ baseGiven = false, base = "", demoDefault = "" } = {}) {
   if (baseGiven) return null;                      // the reader chose it, so it is not the demo's to clear
   if (!base || !demoDefault) return null;          // nothing to compare: say no

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1c5ecbdefb9e379d1a7407aabfd3efc9384ffa44",
-  "version": "0.3.2-beta.10"
+  "commit": "aa58558b3b09fbf5b1c83010291d340167d438d8",
+  "version": "0.3.2-beta.11"
 }

package/docs/architecture/05-config-governance.md

@@ -542,7 +542,7 @@ change. The product's known mirror classes:
 | CF Access team / AUD / domain gates | edge (dashboard) + each fronted unit's inline env | staff or company lockout, service by service |
 | `TRADEMARK_MCP_TOKEN_SECRET` | EnvironmentFile + any integrator-hosted artifacts-MCP env block | run-bound `user` tokens fail verification |
 | Register-provider credentials | EnvironmentFile + integrator plugin config (when both consume the provider) | one consumer silently unauthenticated |
-| Profiles/skills store paths | EnvironmentFile + service unit files (+ integrator MCP env) | roster-mismatch class (the PR #14 incident) |
+| Profiles/skills store paths | EnvironmentFile + service unit files (+ integrator MCP env) | roster-mismatch class: a door serving the bundled demo roster instead of the real one |
 | Pool root | code default + units + web-server file root (+ integrator MCP env) | reports publish where nothing serves |
 | Public hostnames | EnvironmentFile (rendered links) + router + edge | dead links / dead routes |