clearotron 0.3.0-beta.1 → 0.3.0-beta.10

package/.env.example

@@ -388,6 +388,26 @@ CLEAROTRON_SUITE_TELEMETRY_DIR=
 # effect: deployment
 CLEAROTRON_DEMO=
 
+# How the reader typed this command, handed from the dispatcher to each verb it runs. `clearotron`
+# runs every verb as a process of its own, so a verb's own argv[1] is `bin/<verb>.mjs` however the
+# reader started it. The dispatcher passes its own argv[1] down in this name, and every command a verb
+# prints for the reader to type next is spelled from it: `clearotron …` after a global install,
+# `npx clearotron …` otherwise. Unset, a verb reads its own argv[1].
+# Set by bin/clearotron.mjs on every verb it runs, never by an operator, so the row is left commented.
+# It is listed for the reason CLEAROTRON_DEMO is: the catalogue is about what an operator can FIND.
+# Read by shared/invocation.mjs.
+# effect: deployment
+# CLEAROTRON_INVOKED_AS=
+
+# Marks an install that has already moved itself out of npm's npx cache. `npx clearotron install` first
+# installs the same version under ~/.local and then runs that copy's install, with this set to 1, so the
+# copy does not try to move itself a second time. Unset, an install running from npx's cache moves.
+# Set by bin/onboard.mjs on the one process it starts, never by an operator, so the row is left
+# commented. It is listed for the reason CLEAROTRON_DEMO is: the catalogue is about what an operator can
+# FIND. Read by bin/onboard.mjs.
+# effect: deployment
+# CLEAROTRON_RELOCATED=
+
 # How many client what-ifs the runner drains at once (default 1). A what-if re-runs ONE stage of a run
 # that already exists, in a sandbox, at a client's request — the owner opened it to clients on
 # 2026-08-27 and ruled SPEND controls out with it ("ignore the call spend"). This is not one.
@@ -538,11 +558,12 @@ CLEAROTRON_DEMO_PROFILES=
 
 # ── The organisation setup names ──────────────────────────────────────────────────────────────────
 #
-# Your organisation's name. `npm run setup` asks for it directly after the sign-in address and writes it
-# here, quoted, so a name holding a `#` survives. The first `clearotron start` files it as the first
+# 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/CONTRIBUTING.md

@@ -12,7 +12,7 @@ the rest — with the file that owns each.
 
 ## What you can run, with nothing but a clone
 
-**Node 22 is a hard floor.** `package.json` declares it, `.nvmrc` pins it, and the free US register
+**Node 22.13 is a hard floor.** `package.json` declares it, `.nvmrc` pins it, and the free US register
 runs on `node:sqlite`. Node 20 will fail in ways that look like your change.
 
 ```bash

package/INSTALL.md

@@ -48,7 +48,8 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
 - **macOS, Linux, or native Windows for the demo; WSL2 for a clearance.** `npx clearotron
   demo` runs anywhere Node does, native Windows included. A real clearance does not: the engine resolves
   the reasoning CLI the POSIX way, so a native-Windows clearance refuses at preflight even with the CLI
-  on `PATH`. On Windows, `wsl --install -d Ubuntu`, then `wsl -d Ubuntu`, and work through this page
+  on `PATH`. Native Windows clearances are planned for a later release. Until then, on Windows,
+  `wsl --install -d Ubuntu`, then `wsl -d Ubuntu`, and work through this page
   from **inside** that distribution. Name it: plain `wsl` can open a minimal image with no apt, no
   curl and no bash, and everything below assumes Ubuntu. A fresh Ubuntu has no Node at all, and
   apt's package is below the floor above, so `npx` answers "not found" before anything of ours runs.
@@ -63,6 +64,15 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
   npx clearotron install
   ```
 
+  Run from `npx`, the install first installs Clearotron under `~/.local`, as `npm install -g --prefix
+  ~/.local` would, and finishes from there. That way the `clearotron` command and your assistant's connection
+  do not point into npm's temporary cache, which npm replaces on an update and deletes when it cleans up.
+  Later, the `update` command updates that copy in place.
+
+  On WSL, a program on the Windows side can hold a port that WSL reports as free, and the browser reaches
+  it first. VS Code's Remote-SSH port forwarding is the common case. If the page that opens is not this
+  install's sign-in, run the same command again with `--port 28802`, or any free number.
+
   A *hosted* deployment needs Linux for one further thing, the systemd outbox trigger —
   [driver/systemd/README.md](driver/systemd/README.md).
 - **A reasoning CLI on your `PATH`, signed in.** This is the prerequisite people miss. Every stage runs
@@ -285,6 +295,71 @@ keeps working throughout.
 provider, so it is safe to run on any machine that has the repository. "Safe anywhere" is about spend,
 not about where it will run — on a packaged tree it refuses, as above.
 
+## 2a. Removing it
+
+An install is not one directory, so removing it is not one command. Everything it writes is listed here.
+Read the list before you delete anything: one of these directories holds your reports.
+
+**Stop it first.** If the product is running in a terminal, Ctrl-C in that terminal. If you installed the
+background services, `clearotron stop` stops them and removes their unit files. `clearotron status` says
+which of the two you have.
+
+**The program.** Installed globally, `npm rm -g clearotron` removes it. Installed by `clearotron install`
+(which is also what a demo run from `npx` leaves behind), it lives in two places under `~/.local`:
+
+```
+~/.local/lib/node_modules/clearotron
+~/.local/bin/clearotron
+```
+
+**The settings, and the keys.** `~/.config/clearotron/.env` holds this install's signing secrets, so
+deleting it invalidates every key it ever issued. Beside it: `~/.config/clearotron/token-denylist`, the
+list of keys you revoked, and `~/.config/clearotron/running`, which records a product running in a
+terminal and is rewritten on every start.
+
+**Your work.** The install keeps it all under one directory, `~/trademark` by default — wherever
+`CLEAROTRON_REPORTS_DIR`'s parent points if you moved it:
+
+```
+~/trademark/pool                              THE REPORTS. Every clearance this install delivered.
+~/trademark/workspace                         the working files of each run, including unfinished ones
+~/trademark/queue                             work ordered and not yet run
+~/trademark/outbox                            what the product prepared to send
+~/trademark/locks                             which runs are in flight
+~/trademark/config                            your companies, their projects and your saved searches
+~/trademark/config/recipes                    the saved searches themselves
+~/trademark/config/profiles                   the company profiles
+~/trademark/grants.json                       who may use this install
+~/trademark/portal-audit.log                  what the portal was asked to do
+~/trademark/portal-local-credential.json      the sign-in this install minted for you
+```
+
+**Keep the pool if you want the reports.** They are finished documents and nothing else reads them: move
+`~/trademark/pool` somewhere of your own and delete the rest. Deleting the pool deletes the clearances.
+
+**The demo, if you ran one.** `~/trademark-demo` holds the demo's own copy of everything above, including
+its own copy of the program under `~/trademark-demo/program`. It is one directory to remove and it shares
+nothing with an install.
+
+**The background services, if you installed them.** `clearotron stop` removes the four unit files; if you
+would rather see them, they are in `~/.config/systemd/user`:
+
+```
+clearotron-portal.service
+clearotron-mcp-face.service
+clearotron-worker.service
+clearotron-client-mcp.service
+```
+
+**And `~/.env`, which only a background install writes.** A service inherits nothing from the terminal
+that installed it, so `clearotron start --background` writes everything those services need into `~/.env`,
+mode 600 — your register credential, your research key and the engine's settings among it. It is not the
+same file as `~/.config/clearotron/.env`, which configures the product when you run it yourself. Delete
+both, or you leave a file of credentials in your home for services that no longer exist.
+
+Nothing else on the machine is ours: no system-wide files, no services outside your own user, and nothing
+in `/etc`, `/usr` or `/var`.
+
 ## 3. Configuration (environment)
 
 Runtime configuration is by environment variable, and there are two ways to supply them.
@@ -490,6 +565,25 @@ matches, the neutral Generic default applies.
 - **Your real customers live outside the repo.** Point `CLEAROTRON_CUSTOMERS_DIR` at your own private
   config store and the engine loads *those* accounts instead. **Same engine, different config path** —
   the code carries no customer identities.
+
+  Two things go with it, and both are refusals rather than preferences:
+
+  - **`PROFILE_REPO_ROOT` moves too.** The customer directory has to sit inside the repository that
+    variable names, because editing a profile is a commit. Point one somewhere new and leave the other
+    behind and the portal and the profile service both refuse to start, naming both variables.
+  - **That repository needs a `user.name` and a `user.email` of its own.** Saves are committed under
+    the name of whoever asked for them, but git also records who *made* the commit, and it will not
+    commit at all without one. A service account usually has no global git identity, so a store created
+    by hand needs its own:
+
+    ```bash
+    git init -b main /srv/clearotron-store
+    git -C /srv/clearotron-store config user.name  "clearotron local install"
+    git -C /srv/clearotron-store config user.email "clearotron@example.com"
+    ```
+
+    `clearotron start` does this for the store it creates. A store you make yourself does not get it,
+    and the symptom is the first save failing at a commit rather than anything about profiles.
 - **Run data is external too.** Published reports, audits, and per-run state go to the archive pool at
   `CLEAROTRON_REPORTS_DIR`. Nothing customer-specific is committed to the repository.
 
@@ -729,12 +823,17 @@ Use the demo to see what this system produces. Use `npx clearotron start` to run
 
 - Generates `PORTAL_SECRET` and `TRADEMARK_MCP_TOKEN_SECRET` and **appends** them to `~/.config/clearotron/.env` at
   mode 600. Append, never rewrite: that file also holds the credentials `npx clearotron install` collected.
+  It also records where saved searches are kept, `CLEAROTRON_RECIPES_DIR` and `RECIPE_REPO_ROOT`, so
+  `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>`.
-- Mints your sign-in passphrase and **prints it once**. Write it down. It is stored as a scrypt digest,
-  nothing can read it back, and no later start reprints it. To get a new one, delete
-  `~/.cordillera/portal-local-credential.json` and start again.
+  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
+  `~/trademark/portal-local-credential.json`, nothing can read it back, and no later start reprints it. To
+  get a new one, run `clearotron passphrase --reset`. An install that has been signing in with
+  `~/.cordillera/portal-local-credential.json`, which earlier versions shared between installs, keeps it.
 
 ### Who you are
 
@@ -744,12 +843,12 @@ You sign in as `<your-username>@localhost` unless you say otherwise:
 npx clearotron start --user you@example.com
 ```
 
-The address is written to `.env`, so it is asked for once. It is also the first person on this
-install: the first start writes it into the grants file (`CLEAROTRON_ACCESS_FILE`, §8) with access to
-everything and both permissions, Run clearances and Manage. Setup asks for your organisation's name
-directly after the address, and the same start files it there as your first organisation. The address
-admits nobody else at its domain; enrolling anyone else is that same file, exactly as on a hosted
-instance.
+Setup does not ask for the address: it writes the local-account form to `.env` and shows it once, in
+its summary, as the address that signs in. An address already in `.env` is kept. It is also the first
+person on this install: the first start writes it into the grants file (`CLEAROTRON_ACCESS_FILE`, §8)
+with access to everything and both permissions, Run clearances and Manage. Setup asks for your
+organisation's name, and the same start files it there as your first organisation. The address admits
+nobody else at its domain; enrolling anyone else is that same file, exactly as on a hosted instance.
 
 **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
@@ -901,12 +1000,19 @@ their own integration work.
 **Two shapes, and the line between them is what your assistant can do — not where it runs.** Ruling
 2026-09-03, on the vendor's own documented behaviour:
 
-1. **An assistant that can launch a local process** — Claude Code, Claude Desktop's local config,
-   Codex CLI, an agent that runs commands. It 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` hands it over per assistant.
-2. **Everything else, wherever it appears to run** — Cowork, ChatGPT, claude.ai, Perplexity, the mobile
-   apps. These need **a publicly reachable HTTPS address**, plus a key. Always.
+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.
+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
+   --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`.
 
 **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

package/README.md

@@ -19,50 +19,62 @@ 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** —
-the engine resolves the reasoning CLI the POSIX way and refuses at preflight otherwise.
+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
 sure, the first command is the one you want.
 
+Removing it later: **[INSTALL.md §2a](INSTALL.md#2a-removing-it)** lists every path an install writes, and
+says which one holds your reports so you can keep them deliberately.
+
 ## Quick start
 
-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
@@ -81,11 +93,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/brandowner.mjs

@@ -119,6 +119,16 @@ const USAGE = `
     --context    a file whose contents become this owner's context pack
     --dry-run    say exactly what would be written, and write nothing
 
+  clearotron brandowner framework <key> <path>
+
+    Point an existing company at a risk framework, as skills/prelim-search/<file>.md.
+    The deck is checked before anything is written: a path that does not resolve, or a
+    manifest that will not load, is refused and the company is left exactly as it was.
+
+    This is the route a company created in the browser gets a framework by. The browser
+    deliberately sets no framework — frameworkPath is code-owned and the profile screen
+    shows it read-only — so without this verb there was no supported route at all.
+
   Exit codes: 0 written and recorded · 1 refused, nothing written · 2 usage
               3 written but NOT recorded — the bundle is written and the store has no record of it
 `;
@@ -266,11 +276,94 @@ export async function add(argv, {
   return { written: true, store, profile, framework, commit, commitError };
 }
 
+/**
+ * Point an existing company at a risk framework.
+ *
+ * THE LINT IS `resolveFramework`, NOT A SECOND OPINION. That function already refuses a path of the
+ * wrong shape, one that does not resolve on this install, and one whose manifest will not load — in the
+ * words the create path uses. A second check here would be a second set of messages to keep in step, and
+ * the one this file could write is the one that would go stale.
+ *
+ * IT REFUSES BEFORE IT WRITES. A framework somebody chose that does not resolve is a mistake, not an
+ * absence, and the company is left exactly as it was — which matters more here than on a create, because
+ * there is an existing company whose rating this would change.
+ *
+ * THE WHOLE PROFILE IS REWRITTEN, one field changed. `defaultWriteProfile` is the one writer, so this
+ * cannot invent a second shape of profile file; the read-modify-write is deliberate and the alternative
+ * — patching a key in place — is how two writers come to disagree about what a bundle contains.
+ */
+export async function framework(argv, {
+  resolution = profileStoreResolution(),
+  out = console.log,
+} = {}) {
+  const [key, path] = argv;
+  if (!key) throw new Refusal(`this command needs a company key.${USAGE}`);
+  if (!path) throw new Refusal(`this command needs a framework path, as skills/prelim-search/<file>.md.${USAGE}`);
+  try { assertProfileKey(key); }
+  catch (e) { throw new Refusal(e?.message ?? String(e)); }
+
+  const store = storeForAdd(resolution);
+  const file = join(store, `${key}.json`);
+  // AN ABSENT COMPANY IS NAMED, not created. `add` is the verb that creates; a typo here would
+  // otherwise write a bundle carrying nothing but a framework path.
+  if (!existsSync(file))
+    throw new Refusal(`no company "${key}" in ${store} — "brandowner add ${key} --name ..." creates one.`);
+
+  // Refuses here, before anything is read for writing.
+  const resolved = resolveFramework(path);
+
+  const profile = JSON.parse(readFileSync(file, "utf8"));
+  const was = profile.frameworkPath ?? null;
+  if (was === resolved.path) {
+    out(`  ${key} already rates under ${resolved.path} — nothing to change.`);
+    return { written: false, store, framework: resolved };
+  }
+  // THE CONTEXT PACK IS READ AND HANDED BACK, because omitting it is not "leave it alone".
+  // `defaultWriteProfile` reads an absent pack as "this company has none" and REMOVES the sibling file.
+  // `add` never meets that branch: it always passes the pack it was given. This verb is the first caller
+  // that rewrites a company which already exists, so it is the first one that can reach it — and setting
+  // a framework would have deleted the company's context pack, and committed the deletion under a
+  // message about the framework. Found in review, driven before the fix: a store holding acme.json and
+  // acme.context.md kept only acme.json.
+  //
+  // Re-writing the pack is deliberate rather than clever. It lands in the commit's file list, git sees
+  // no change in a pack that was already stored the way this writer stores it, and the commit still
+  // carries only the profile. NOT byte-for-byte in every case: `defaultWriteProfile` trims and ends
+  // with one newline, so a pack hand-edited with blank lines around its text comes back without them.
+  // The words are untouched, which is what the arm below checks. A pack holding nothing but whitespace
+  // is still removed, which is what every other reader of this store already means by an empty pack.
+  const packPath = join(store, CONTEXT_PACK_FILE(key));
+  const contextPack = existsSync(packPath) ? readFileSync(packPath, "utf8") : "";
+  const { files } = defaultWriteProfile({
+    profileDir: store, key, profile: { ...profile, frameworkPath: resolved.path }, contextPack,
+  });
+
+  const repoRoot = resolveStoreRepoRoot({ names: ["CLEAROTRON_CUSTOMERS_DIR"], fallback: store }).root;
+  const audit = makeCommittableAudit({ auditPath: join(store, "audit.jsonl"), repoRoot });
+  const gitCommit = makeStoreCommit({ repoRoot, what: "customers" });
+  let by = "unknown";
+  try { by = userInfo().username || "unknown"; } catch { /* no passwd entry — the row still gets written */ }
+  const { commit, commitError } = commitWithAuditRow({
+    audit, gitCommit, files, by,
+    message: `company ${key} rates under ${resolved.path}${was ? ` (was ${was})` : ""}`,
+  });
+
+  out(`  ${key} now rates under ${resolved.path}${was ? ` — was ${was}` : " — it had none of its own"}.`);
+  if (commit) out(`  recorded ${commit}`);
+  if (commitError) out(`  WROTE THE CHANGE BUT DID NOT RECORD IT: ${commitError} — the audit line is on disk; fix the store's git state`);
+  return { written: true, store, framework: resolved, was, commit, commitError };
+}
+
 async function main() {
   const [sub, ...rest] = process.argv.slice(2);
   if (!sub || sub === "--help" || sub === "-h" || sub === "help") { console.log(USAGE); process.exit(sub ? 0 : 1); }
-  if (sub !== "add") { console.error(`brandowner: no such action "${sub}". One of: add`); process.exit(2); }
+  if (sub !== "add" && sub !== "framework") { console.error(`brandowner: no such action "${sub}". One of: add, framework`); process.exit(2); }
   try {
+    if (sub === "framework") {
+      const r = await framework(rest);
+      if (r?.commitError) process.exit(3);
+      return;
+    }
     // WROTE-BUT-DID-NOT-RECORD IS NOT SUCCESS. The write stands — rolling a written bundle back
     // would lose the operator's work over a git fault they can fix — but a scripted onboarding
     // reading exit 0 concludes the store recorded it, and the store did not. Exit 3 says both

package/bin/connect.mjs

@@ -45,8 +45,9 @@ import { homedir, userInfo } from "node:os";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 import { createServer } from "node:net";
-import { CONNECT_CLIENTS, clientById, whatItNeeds } from "../shared/connect-clients.mjs";
+import { CONNECT_CLIENTS, WHERE_FLAG, clientById, leadRouteFor, plainStep, whatItNeeds } from "../shared/connect-clients.mjs";
 import { stdioConnectFor, STDIO_SHAPES } from "../shared/stdio-connect.mjs";
+import { isWsl } from "../shared/wsl.mjs";
 import { defaultDenylistPath, clientDoorAddress, clientDoorPort, clientDoorState, enablePlan, applyEnablePlan, describeChange, recordConnectKey, CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { mintToken, tokenId, resolvePerson, loadGrants } from "../shared/scope.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
@@ -205,7 +206,8 @@ function deploymentHas(env = process.env) {
   return {
     // EVERY SHAPE, RESOLVED ONCE. A row picks its own; nothing here knows a client's name.
     stdioRoutes: Object.fromEntries(Object.keys(STDIO_SHAPES).map((shape) =>
-      [shape, stdioConnectFor(shape, { workDir: env.CLEAROTRON_WORK_DIR || null })])),
+      [shape, stdioConnectFor(shape, { workDir: env.CLEAROTRON_WORK_DIR || null, reportsDir: env.CLEAROTRON_REPORTS_DIR || null })])),
+    wsl: isWsl({ env }),
     // WHERE THE DOOR BINDS — not an address handed to any assistant. It is the loopback address the
     // unit listens on, and `enablePlan` needs it to write the unit. It used to be passed to the
     // resolver as `localAddress` and served to Cowork as somewhere to connect, which is the false
@@ -555,17 +557,12 @@ async function render(offer, have, { dryRun, running, allowMove = false }) {
     return 1;
   }
 
-  if (offer.route === "disk" || (offer.route === "either" && offer.command)) {
-    // A COMMAND AND A CONFIG BLOCK ARE NOT THE SAME INSTRUCTION, and saying "run this" over a TOML
-    // block is how a reader pastes four lines into a shell. The shape says which it is.
-    const s = offer.stdio;
-    say(s?.kind === "config"
-      ? `  Add this to ${s.where}:`
-      : "  Run this once, on this machine:");
+  if (offer.route === "disk") {
+    // THE ROW'S OWN STEPS, and nothing written here. A command and a settings block are not the same
+    // instruction — saying "run this" over a TOML block is how a reader pastes four lines into a shell —
+    // and the steps already say which each one is and where it goes.
+    printSteps(offer, null);
     say("");
-    for (const line of String(offer.command).split("\n")) say(`    ${line}`);
-    say("");
-    if (s?.after) { say(`  ${s.after}`); say(""); }
     say(`  ${offer.note}`);
     return 0;
   }
@@ -621,22 +618,40 @@ async function render(offer, have, { dryRun, running, allowMove = false }) {
   }
 
   say(`  Address:  ${offer.address}`);
-  if (key) say(`  Key:      ${key}`);          // printed once, stored nowhere
-  // ── AND WHERE TO PUT THEM ( — F35) ───────────────────────────────────────
-  //
-  // The owner was left with two strings and no destination: *"I don't know how to connect it in Claude
-  // Cowork with those details."* The steps were DEFINED IN THE PRODUCT the whole time — `withSteps`
-  // computes them for every offer, interpolating this install's own address and operator — and this
-  // verb simply never printed them. Nothing new is authored here; a second set of instructions written
-  // at the CLI would drift from the page's, which is the defect connect-clients-are-data exists against.
+  // Printed once, stored nowhere — and only here when no step hands it over. A step whose copy carries
+  // the key prints it inside the line the reader pastes, which is the one place it is needed.
+  const keyInSteps = (offer.steps ?? []).some((s) => s.copy?.kind === "secret");
+  if (key && !keyInSteps) say(`  Key:      ${key}`);
+  printSteps(offer, key);
+  say("");
+  say(`  ${offer.note}`);
+  return 0;
+}
+
+/**
+ * The offer's own steps, numbered, with each copy printed under the step that hands it over.
+ *
+ * ── AND WHERE TO PUT THEM ( — F35) ───────────────────────────────────────
+ *
+ * The owner was left with two strings and no destination: *"I don't know how to connect it in Claude
+ * Cowork with those details."* The steps were DEFINED IN THE PRODUCT the whole time and this verb simply
+ * never printed them. Nothing is authored here; a second set of instructions written at the CLI would
+ * drift from the page's, which is the defect connect-clients-are-data exists against. A secret copy is
+ * printed with the key this press minted put in its slot — the page does the same substitution into the
+ * clipboard — and with no key (a dry run) the step prints and its copy does not.
+ */
+function printSteps(offer, key) {
   if (offer.steps?.length) {
     say("");
     say(`  In ${offer.client?.name ?? "your assistant"}:`);
-    offer.steps.forEach((step, n) => say(`    ${n + 1}. ${step}`));
+    offer.steps.forEach((step, n) => {
+      say(`    ${n + 1}. ${plainStep(step.text)}`);
+      const c = step.copy;
+      const text = !c ? null : c.kind === "secret" ? (key ? c.template.split(c.slot).join(key) : null) : c.text;
+      if (text) { say(""); for (const line of text.split("\n")) say(`         ${line}`); say(""); }
+      if (step.hint) say(`       ${plainStep(step.hint)}`);
+    });
   }
-  say("");
-  say(`  ${offer.note}`);
-  return 0;
 }
 
 async function main() {
@@ -654,6 +669,9 @@ async function main() {
     say("  not about you.");
     say("");
     say("    --client <name>   skip the question (see --list for the names)");
+    say("    --where here      your assistant runs on this machine: it starts the software itself");
+    say("    --where elsewhere your assistant runs somewhere else and reaches this install over the");
+    say("                      internet, with a key made for you now");
     say("    --list            the assistants this build knows");
     say("    --dry-run         say what would change, change nothing");
     say("    --allow-checkout-move");
@@ -663,7 +681,7 @@ async function main() {
     say("");
     return 0;
   }
-  const known = new Set(["--client", "--list", "--dry-run", "--allow-checkout-move", "--help", "-h"]);
+  const known = new Set(["--client", "--where", "--list", "--dry-run", "--allow-checkout-move", "--help", "-h"]);
   const unknown = argv.filter((a) => a.startsWith("--") && !known.has(a));
   if (unknown.length) {
     console.error(`connect: unrecognised flag(s): ${unknown.join(", ")}`);
@@ -671,6 +689,12 @@ async function main() {
     process.exit(2);
   }
   const dryRun = argv.includes("--dry-run");
+  const w = argv.indexOf("--where");
+  if (w >= 0 && !Object.hasOwn(WHERE_FLAG, argv[w + 1] ?? "")) {
+    console.error(`connect: --where takes one of: ${Object.keys(WHERE_FLAG).join(", ")}`);
+    process.exit(2);
+  }
+  let route = w >= 0 ? WHERE_FLAG[argv[w + 1]] : null;
   // F40 — reason about the RUNNING product from the units' own environment, not this CLI's env file.
   const running = runningEnv();
   const have = deploymentHas(running.env);
@@ -712,9 +736,30 @@ async function main() {
       chosen = CONNECT_CLIENTS[Number(answer) - 1] ?? clientById(answer);
     } finally { rl.close(); }
     if (!chosen) { console.error("connect: not one of the listed assistants."); process.exit(2); }
+    // THE SECOND QUESTION, ASKED ONLY WHEN IT HAS TWO ANSWERS — the page's own, in the terminal's words.
+    // Where only one route is served here, asking would offer a choice whose other half cannot work.
+    const both = ["disk", "public-http"].filter((r) => whatItNeeds(chosen, have, r)?.served);
+    if (!route && both.length > 1) {
+      say("");
+      say("  Where does it run?");
+      say("");
+      say("    1) On this machine — it starts the software itself, nothing to open up");
+      say("    2) Somewhere else — it reaches this install over the internet, with a key made for you now");
+      say("");
+      const rl2 = createInterface({ input: stdin, output: stdout });
+      try {
+        const answer = (await rl2.question("  1-2: ")).trim();
+        route = answer === "1" ? "disk" : answer === "2" ? "public-http" : null;
+      } finally { rl2.close(); }
+      if (!route) { console.error("connect: answer 1 or 2."); process.exit(2); }
+    }
+    route ??= both[0] ?? chosen.lead;
   }
 
-  return await render(whatItNeeds(chosen, have), have, { dryRun, running, allowMove: argv.includes("--allow-checkout-move") });
+  // NAMED WITHOUT --where: the route this id had before every row took both, so a scripted
+  // `--client cowork` still mints a key and `--client codex` still prints a settings block.
+  route ??= leadRouteFor(argv[i + 1]);
+  return await render(whatItNeeds(chosen, have, route), have, { dryRun, running, allowMove: argv.includes("--allow-checkout-move") });
 }
 
 // THE DISPATCH RUNS ONLY WHEN THIS FILE IS THE COMMAND. Without the guard, importing