clearotron 0.3.0-beta.1 → 0.3.0-beta.2

package/.env.example

@@ -388,6 +388,17 @@ 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=
+
 # 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,8 +549,8 @@ 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

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.
@@ -732,9 +733,10 @@ Use the demo to see what this system produces. Use `npx clearotron start` to run
 - 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.
+- 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 +746,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

package/README.md

@@ -36,8 +36,9 @@ npm install -g clearotron
 ```
 
 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.
+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.
 
 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

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/onboard.mjs

@@ -72,11 +72,11 @@ import { styleFor, banner } from "../shared/tty-style.mjs";   // — weight wher
 import { bracketAsciiCells, BRAND } from "../shared/brand.mjs";      // F18 — the mark, from the geometry the SVG already uses
 // THE REFUSALS ABOUT THE SIGN-IN ADDRESS ITSELF, shared with `bin/start.mjs`. Two copies would be a
 // wizard that accepts an address the launcher then sends back.
-import { addressRefusal } from "../shared/staff-domain.mjs";
 import { join, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { delimiter } from "node:path";
 import { Writable } from "node:stream";
+import { looksLikeAKey, yesNoEchoOf } from "../shared/yes-no-echo.mjs";   // a yes/no question echoes only a yes/no answer
 
 import { envLocalPath, activeEnvPath, loadEnvLocal, LEGACY_ENV_LOCAL_LOCATION } from "../shared/env-local.mjs";
 import { writeSecretFile } from "../shared/secret-file.mjs";   // one atomic write for every file holding credentials
@@ -97,6 +97,7 @@ import { processTable } from "../shared/process-table.mjs";   // — /proc is no
 import { programsFromAnotherCheckout } from "../shared/checkout-move.mjs";
 import { entrypointOf } from "../driver/systemd/install-census.mjs";         // one ExecStart parser
 import { overlayReport, renderOverlayReport } from "../shared/doctrine-overlay.mjs";   // — the doctor reports the overlay
+import { whereSavesGo } from "../shared/store-in-repo.mjs";   // — doctor says where a portal save goes once it is committed
 import { engineInventory, engineMode, ENGINE_MODES } from "../driver/config-inventory.mjs";   //
 import { probeEngineTurn, probeFailureText, PROBE_MODEL, PROBE_TIMEOUT_SEC, engineEnvKeys } from "../driver/engine/probe.mjs";
 import { runRequiredNames, missingRequirements, REGISTER_ENV, ENGINE_ENV } from "../driver/run-requirements.mjs";   // the order-time gate's own question, asked here rather than restated
@@ -594,13 +595,17 @@ const present = (v) => typeof v === "string" && v.trim() !== "";
 /**
  * Ask who signs in, and what their organisation is called.
  *
- * ── WHY THE ADDRESS IS ASKED AT ALL ─────────────────────────────────────────────────────────────────
+ * ── THE ADDRESS IS NOT ASKED (ruling, 2026-09-10) ──────────────────────────────────────────────────
  *
- * Setup never asked for an address. `clearotron start` therefore took one from `--user`, from
- * `PORTAL_LOCAL_USER`, or from the local account as `<account>@localhost`. An outside install reached a
- * state nobody chose that way: an assistant filled a documentation address into the environment file on
- * the operator's behalf, because this wizard had no prompt for it. So the address is asked for here,
- * where a person is definitionally present.
+ * It was, for a while. `clearotron start` took an address from `--user`, from `PORTAL_LOCAL_USER`, or
+ * from the local account as `<account>@localhost`, and an outside install reached a state nobody chose
+ * that way: an assistant filled a documentation address into the environment file on the operator's
+ * behalf. On a local install the question buys nothing the local-account form does not give, so it is
+ * gone: the address is `<account>@localhost`, used without a question and shown once, in the summary's
+ * "signs in as" line. Anyone behind a login system changes it in the grants file.
+ *
+ * AN ADDRESS THE SETTINGS FILE ALREADY HOLDS IS KEPT. A re-run of setup must not sign out the person an
+ * earlier run enrolled: their passphrase and their grants entry are both keyed on that address.
  *
  * WHAT IT NO LONGER DECIDES. The part after its `@` used to decide who was an administrator: everyone at
  * that domain was staff. That rule is deleted, with the question about granting the domain and the
@@ -608,47 +613,28 @@ const present = (v) => typeof v === "string" && v.trim() !== "";
  * written as their own entry in the grants file by `clearotron start` (`installerGrants`), and it admits
  * nobody else whatever its domain.
  *
- * TWO REFUSALS ABOUT THE ADDRESS ITSELF STAY: not a single email address, and a public or reserved
- * domain (shared/staff-domain.mjs, shared with `clearotron start` so the two refuse the same addresses).
+ * THE TWO REFUSALS ABOUT THE ADDRESS ITSELF are `clearotron start`'s (shared/staff-domain.mjs): not a
+ * single email address, and a public or reserved domain. The wizard no longer takes an address to refuse.
  *
- * THE ORGANISATION'S NAME, directly after the address and required. It is the organisation the install
+ * THE ORGANISATION'S NAME, the one question this step asks, and required. It is the organisation the install
  * starts with and the label the portal shows for it; `clearotron start` files it in the grants file the
  * first time that file holds none, and it is renamed there. WRITTEN QUOTED, because the loader reads
  * `.env` with Node's `parseEnv`, which ends an unquoted value at `#` and trims it — measured: "Café #1
  * Sàrl" written bare comes back "Café". Quoted it survives whole, except a double quote, which ends the
  * value, so a name holding one is sent back.
  *
- * THE DEFAULT IS THE LOCAL ACCOUNT AND NOTHING ELSE — not the git author, not the hostname, not a shell
- * variable. The address that becomes the first person comes from the person, or from the one source that
- * cannot name a second person.
+ * THE ADDRESS IS THE LOCAL ACCOUNT AND NOTHING ELSE — not the git author, not the hostname, not a shell
+ * variable: the one source that cannot name a second person.
  *
  * `io` IS INJECTED for the reason `offerUsptoSync`'s is: the branches that matter are the answers that
  * must be sent back, and closed over a terminal they are asserted nowhere. Returns the `.env` keys to
  * write and nothing else.
  */
-export async function askSignIn(io, { localAccount = "user" } = {}) {
+export async function askSignIn(io, { localAccount = "user", existing = null } = {}) {
   const { askValue, ok = () => {}, problem = () => {} } = io;
-  const localDefault = `${localAccount}@localhost`;
-  prose("The portal admits one address on this install, and that address is the first person on it:",
-        "access to everything, with both permissions — Run clearances and Manage. Enter accepts the",
-        "local-account form, which is this machine and nobody else.");
-  let address;
-  for (;;) {
-    const typed = String(await askValue("Sign-in address:", { def: localDefault })).trim().toLowerCase();
-    if (!typed.includes("@") || typed.indexOf("@") !== typed.lastIndexOf("@")) {
-      problem(`"${typed}" is not a single email address. The portal refuses a multi-@ identity outright, `
-        + "so this would sign in and then be denied at the door.");
-      continue;
-    }
-    // The refusal's own sentence, never a second copy: `clearotron start` prints these same words when it
-    // meets the same address, and two wordings of one refusal is how a reader comes to believe they have
-    // met two different problems.
-    const refusal = addressRefusal(typed);
-    if (refusal) { problem(refusal); continue; }
-    address = typed;
-    break;
-  }
-  ok(`${address} — the first person on this install, with access to everything.`);
+  // Returned rather than left to the writer to carry, so the address in force is written whichever file
+  // it was read from.
+  const address = String(existing ?? "").trim() || `${localAccount}@localhost`;
   for (;;) {
     const name = String(await askValue("Your organisation's name:") ?? "").trim();
     if (!name) {
@@ -1770,6 +1756,47 @@ export async function runCheck() {
     } catch (e) {
       info(`could not resolve the profile store from here (${String(e?.message ?? e).slice(0, 80)}) — read a run's \`profile-store\` line instead`);
     }
+
+    // ── AND WHERE A SAVE GOES ONCE IT IS COMMITTED ─────────────────────────────────────────────────────
+    //
+    // A save through the portal commits into the store's repository and stops there. Whether it then
+    // leaves this machine is a property of that repository, answered by `whereSavesGo` beside the
+    // committer, which carries the measurement: a store inside a checkout that tracks a remote branch has
+    // its saves published by the next person who syncs or pushes that checkout.
+    //
+    // `warn`, NEVER `problem`, and the exit contract near the top of this file is why. rc 1 means
+    // something the operator set is not doing what they think it is. A store in a repository they push is
+    // doing exactly what it was set up to do; the danger is somebody else's ordinary git work in the same
+    // checkout, which this command cannot see. So the line says it, says when it is fine, and leaves the
+    // exit status alone.
+    //
+    // THE SERVICES' STORE on a hosted box, for the reason the roster lines above give. When their
+    // environment could not be read nothing is judged here, and the lines above already said so.
+    {
+      const storeSet = hosted ? (serviceKnown ? effectiveForService("CLEAROTRON_CUSTOMERS_DIR") : null) : effective("CLEAROTRON_CUSTOMERS_DIR");
+      const storeDir = storeSet?.v || null;
+      if (storeDir && existsSync(storeDir)) {
+        const w = whereSavesGo(storeDir);
+        if (w.state === "publishes") {
+          const waiting = w.ahead > 0 ? `, and ${w.ahead} commit(s) made there have not been pushed yet` : "";
+          const how = w.via && w.via !== "tracking"
+            ? `whose branch ${w.branch} tracks no remote branch, but a bare \`git push\` there sends it to ${w.upstream} (${w.via})`
+            : `whose branch ${w.branch} tracks ${w.upstream}`;
+          warn(`saves to ${storeDir} are committed in ${w.root}, ${how} — `
+            + `whoever next syncs or pushes that checkout publishes them${waiting}. Fine if you publish this store `
+            + "on purpose; if other work happens in that checkout, give the store a repository of its own with no remote");
+        } else if (w.state === "stays-here") {
+          ok(`saves to ${storeDir} are committed in ${w.root}, `
+            + (w.branch ? `whose branch ${w.branch} tracks no remote branch` : "which is not on a branch")
+            + " — nothing carries them off this machine unless someone pushes them by name");
+        } else if (w.state === "not-a-repository") {
+          warn(`${storeDir} is not inside a git repository, so a save through the portal is refused rather than `
+            + "recorded until it is");
+        } else {
+          info(`could not ask git where saves to ${storeDir} go (${w.why}) — a failure to look, not a finding`);
+        }
+      }
+    }
   }
 
   // — WHICH DOCTRINE FILES THIS INSTALL OVERRIDES, AND WHETHER OURS HAVE MOVED UNDER THEM.
@@ -2259,12 +2286,34 @@ export async function runCheck() {
   // the provider's own capability rather than a number typed here.
   if (PROBE_PROVIDERS) {
     say("\n  Register lane — proven, not inferred");
+    // THE PROBE ASKS WITH WHAT THE SECTION ABOVE PRINTED. That section reads the environment first and
+    // this install's env file behind it, and says which: `signa (.env)`. This process does not apply the
+    // file — `doctor` is not a CLI entry in shared/env-local.mjs, because reading is not applying — so the
+    // probe took its provider from a module constant fixed from the shell alone, and its key from the
+    // shell at call time. A provider or key kept only in the file, which is where setup writes them,
+    // came back "not set" or "absent" directly under the line that had just printed it. Measured
+    // 2026-09-10 on a fresh install.
+    //
+    // So the provider is resolved from the same reading, and the provider's own variables, the ones the
+    // section above lists, are placed in this process for the probe and put back after it: the adapter
+    // reads them from the environment when it is called. Nothing else moves.
+    const placed = [];
     try {
       const [{ activeProvider }, { makeLaneProbe, probeSpend, DEFAULT_CONTROLS, loadProviderCapabilities }] = await Promise.all([
         import(pathToFileURL(join(REPO, "driver", "driver.config.mjs")).href),
         import(pathToFileURL(join(REPO, "providers", "_shared", "lane-probe.mjs")).href),
       ]);
-      const adapter = activeProvider();
+      const chosen = effective("CLEAROTRON_DATABASE");
+      const adapter = activeProvider(chosen ? { CLEAROTRON_DATABASE: chosen.v } : null);
+      const spec = PROVIDERS.find((p) => p.id === adapter?.id);
+      const names = spec ? [...spec.credentials, ...(spec.optionalCredentials ?? [])]
+        : [adapter?.credEnv, ...(adapter?.credEnvAlso ?? [])].filter(Boolean);
+      for (const k of ["CLEAROTRON_DATABASE", ...names]) {
+        const e = effective(k);
+        if (e?.from !== ".env") continue;   // unset, or the environment already carries it
+        placed.push([k, Object.hasOwn(process.env, k), process.env[k]]);
+        process.env[k] = e.v;
+      }
       // NOT `adapter.capabilities` — that is null on every adapter, and reading it announced a LOCAL
       // index as a billable search. The declaration lives in the provider's own module. (issue 1871)
       const caps = await loadProviderCapabilities(REPO, adapter?.id);
@@ -2293,6 +2342,10 @@ export async function runCheck() {
     } catch (e) {
       // A probe that could not run says so. It is not evidence about the credential either way.
       info(`the register lane could not be probed: ${String(e?.message ?? e)}`);
+    } finally {
+      // EVERY ONE PUT BACK, including those that were absent: the sections below read this process's
+      // environment, and must not report a value from the file as though the shell had set it.
+      for (const [k, had, v] of placed) { if (had) process.env[k] = v; else delete process.env[k]; }
     }
 
     const pxKey = effective("PERPLEXITY_API_KEY");
@@ -2766,6 +2819,12 @@ export async function runCheck() {
 // ── CLI gate ─────────────────────────────────────────────────────────────────────────────────────────
 // Everything above is importable: the helpers are what the tests exercise directly, and importing this
 // file must not start a wizard. Same gate driver/dev-portal.mjs uses.
+// SETUP'S ONE READLINE KEEPS NO HISTORY. Readline remembers recent answers for the up-arrow, and a key
+// typed at a masked prompt, or pasted at a yes/no one, is an answer like any other: an up-arrow at the
+// next question brought it back in full, showed it and submitted it. Setup never needs an earlier answer
+// back. Exported so the test drives the options this file uses; above the call below, which reads it.
+export const SETUP_READLINE = Object.freeze({ terminal: true, historySize: 0 });
+
 if (!isEntrypoint(import.meta.url)) {
   // imported, not run — do nothing else
 } else {
@@ -2795,26 +2854,50 @@ if (!input.isTTY) {
 // in whatever the reader pastes into a bug report. So the echo is muted while a secret is being typed:
 // the output stream readline writes through drops everything while `muted` is set.
 let muted = false;
+// AND WHILE A YES/NO QUESTION IS OPEN, only what can still become its answer is echoed
+// (shared/yes-no-echo.mjs), so a key pasted there is never shown. `rl` is read only while one is open.
+let yesNo = false;
 const maskedOutput = new Writable({
-  write(chunk, enc, cb) { if (!muted) output.write(chunk, enc); cb(); },
+  write(chunk, enc, cb) {
+    if (!muted) {
+      const out = yesNo ? yesNoEchoOf(String(chunk), { line: rl.line, prompt: rl.getPrompt() }) : chunk;
+      if (out.length) output.write(out, yesNo ? undefined : enc);
+    }
+    cb();
+  },
 });
-const rl = createInterface({ input, output: maskedOutput, terminal: true });
+const rl = createInterface({ input, output: maskedOutput, ...SETUP_READLINE });
 const askRaw = async (q) => (await rl.question(q)).trim();
 const askSecretRaw = async (q) => {
   output.write(q);
   muted = true;
   try { return (await rl.question("")).trim(); } finally { muted = false; output.write("\n"); }
 };
-/** Yes/no with an explicit default. Enter takes the default; nothing else is guessed at. */
-const confirm = async (q, def = true) => {
+// A YES/NO READ: the echo is filtered for exactly as long as the question is open (see maskedOutput).
+const askYesNo = async (q) => { yesNo = true; try { return (await rl.question(q)).trim(); } finally { yesNo = false; } };
+/**
+ * Yes/no with an explicit default. Enter takes the default; nothing else is guessed at, except a key.
+ *
+ * A question that offers to take a key (`key: true`) accepts one pasted as the answer. The echo has
+ * already kept it off the screen, and asking for it a second time would only invite a second paste.
+ * Every other yes/no question still says "Please answer y or n." to anything that is not one.
+ */
+const confirmOrKey = async (q, def = true, { key = true, what = "key" } = {}) => {
   for (;;) {
-    const a = (await askRaw(`  ${q} ${def ? "[Y/n]" : "[y/N]"} `)).toLowerCase();
-    if (a === "") return def;
-    if (["y", "yes"].includes(a)) return true;
-    if (["n", "no"].includes(a)) return false;
+    const raw = await askYesNo(`  ${q} ${def ? "[Y/n]" : "[y/N]"} `);
+    const a = raw.toLowerCase();
+    if (a === "") return { yes: def, value: null };
+    if (["y", "yes"].includes(a)) return { yes: true, value: null };
+    if (["n", "no"].includes(a)) return { yes: false, value: null };
+    if (key && looksLikeAKey(raw)) {
+      info(`that looks like the ${what} itself, so it is taken as the answer. It was not shown.`);
+      info(`received — ${raw.length} characters, ending …${raw.slice(-4)}`);
+      return { yes: true, value: raw };
+    }
     say("  Please answer y or n.");
   }
 };
+const confirm = async (q, def = true) => (await confirmOrKey(q, def, { key: false })).yes;
 /**
  * — `skippable` IS THE WHOLE ANSWER TO "WHICH PROMPTS MAY BE LEFT EMPTY", DECIDED ONCE.
  *
@@ -3197,8 +3280,11 @@ try {
       // named, and the re-probe is the proof either way.
       if (eng.headless) {
         info(`on a box with no browser: run \`${eng.headless.cmd}\`${eng.headless.tokenEnv ? " (from any machine you can sign in on)" : " here"}.`);
-        if (eng.headless.tokenEnv && await confirm(`Did that give you a token to paste? Capture it into ${eng.headless.tokenEnv} now`, false)) {
-          const tok = await askValue(`${eng.headless.tokenEnv}:`, { secret: true, skippable: true, skipped: "Nothing captured." });
+        if (eng.headless.tokenEnv) {
+          // A TOKEN PASTED AT THE YES/NO IS THE ANSWER (confirmOrKey): taken, never shown, not asked for twice.
+          const answer = await confirmOrKey(`Did that give you a token to paste? Capture it into ${eng.headless.tokenEnv} now`, false, { what: "token" });
+          const tok = answer.value ?? (answer.yes
+            ? await askValue(`${eng.headless.tokenEnv}:`, { secret: true, skippable: true, skipped: "Nothing captured." }) : null);
           if (tok !== null) {
             candidate[eng.headless.tokenEnv] = tok;
             authEnv[eng.headless.tokenEnv] = tok;   // the re-probe below must prove the lane WITH it
@@ -3292,7 +3378,10 @@ try {
     if (present(candidate[k])) { ok(`${k} already adopted from your environment`); continue; }
     info(`${k} is optional. Without it, the offices it serves are DISCLOSED as deferred coverage rather`);
     info("  than searched — the run still works and still tells the truth about what it did not reach.");
-    if (await confirm(`Set ${k} now?`, false)) candidate[k] = await askValue(`${k}:`, { secret: true });
+    // A VALUE PASTED AT THE YES/NO IS THE ANSWER (confirmOrKey), as at every question that leads to a secret.
+    const answer = await confirmOrKey(`Set ${k} now?`, false);
+    if (answer.value) candidate[k] = answer.value;
+    else if (answer.yes) candidate[k] = await askValue(`${k}:`, { secret: true });
     else info(`Skipped. Build the index later with: ${invocationPrefix()}clearotron sync`);
   }
   if (registerSelected) {
@@ -3363,7 +3452,10 @@ try {
       if (adapter.obtain) say(`  Where to get one: ${adapter.obtain}.`);
       if (!present(candidate[name])) {
         const skippedLine = `Skipped. You can add ${name} later; until then: ${adapter.absentMeans ?? "the lane stays off"}.`;
-        if (await confirm(`Enter a ${adapter.label} API key now?`, true)) {
+        // A KEY PASTED AT THE YES/NO IS THE ANSWER (confirmOrKey): taken, never shown, not asked for twice.
+        const answer = await confirmOrKey(`Enter a ${adapter.label} API key now?`, true);
+        if (answer.value) candidate[name] = answer.value;
+        else if (answer.yes) {
           const v = await askValue(`${adapter.label} key:`, { secret: true, skippable: true, skipped: skippedLine });
           if (v !== null) candidate[name] = v;
         } else info(skippedLine);
@@ -3586,18 +3678,20 @@ try {
   say("  fallback — falls through by name, so an empty store is a working install. Your own customers");
   say("  are added here by name; the bundled demo customers never show through into your roster.");
 
-  // 7c ── WHO SIGNS IN, AND WHAT THEIR ORGANISATION IS CALLED
+  // 7c ── YOUR ORGANISATION, AND WHO SIGNS IN
   //
-  // The address is the first person on the install and the name is its first organisation. The whole
+  // The name is the install's first organisation. The address is not asked: it is the local account, or
+  // the one the settings file in force already holds, and the summary below shows it once. The whole
   // reasoning, including the domain rule this step no longer writes, is on `askSignIn` above.
-  section("Who signs in");
+  section("Your organisation");
   const localAccount = (() => {
     try { return userInfo().username || "user"; } catch { return "user"; }
   })();
-  // ONE CALL SITE. The loop itself lives in `askSignIn` so that the branches that matter — an address
-  // that must be sent back, a name that is missing — are reachable without a terminal. The same seam
-  // and the same reason as `offerUsptoSync`.
-  Object.assign(candidate, await askSignIn({ askValue, ok, problem }, { localAccount }));
+  const signInKept = readEnvFile(READ_ENV_PATH()).PORTAL_LOCAL_USER ?? null;
+  // ONE CALL SITE. The loop itself lives in `askSignIn` so that the branches that matter — a name that is
+  // missing, or one the settings file cannot keep — are reachable without a terminal. The same seam and
+  // the same reason as `offerUsptoSync`.
+  Object.assign(candidate, await askSignIn({ askValue, ok, problem }, { localAccount, existing: signInKept }));
 
   // 8 ── the engine's own preflight over the whole candidate
   //
@@ -3653,6 +3747,11 @@ try {
   // rather than fall back, so a permissions fault can never silently swap a customer's framework for the
   // Generic default). Nothing is written INTO them — see the note at step 7b.
   for (const k of ["CLEAROTRON_CUSTOMERS_DIR"]) mkdirSync(candidate[k], { recursive: true });
+  // AND THE SKILLS FOLDER THE NOTE AT 7b TELLS THE READER TO USE, created and NOT configured.
+  // CLEAROTRON_INSTRUCTIONS_DIR stays unset, so the engine uses the product's own instructions, and the
+  // portal reads an empty folder the same way: it overrides nothing. It is here so that the place an
+  // override goes exists, and so the line below is true of both folders it describes.
+  mkdirSync(join(cfg, "skills"), { recursive: true });
   ok(`configuration directories created under ${cfg} (empty — the bundled instructions and the generic fallback show through; customers are yours to add)`);
 
   // 9a ── PUT THE VERB ON THIS OPERATOR'S PATH
@@ -3723,6 +3822,8 @@ try {
   say(`\n  ${style.bold("Setup finished.")} Nothing here needs running again.\n`);
   say("  What this box has now:");
   for (const line of [
+    // THE ONE PLACE THE ADDRESS IS SHOWN (ruling, 2026-09-10): setup no longer asks for it.
+    stateLine("signs in as", candidate.PORTAL_LOCAL_USER, "the local account"),
     stateLine("register", candidate.CLEAROTRON_DATABASE, "no register, so every search refuses until one is chosen"),
     stateLine("web research", present(candidate.PERPLEXITY_API_KEY) ? "a key" : "", "a clearance stops before it starts, and names the missing key; a knockout search runs and discloses the half it skipped"),
     stateLine("data directory", candidate.CLEAROTRON_REPORTS_DIR, "unset"),