clearotron 0.3.0-beta.3 → 0.3.0-beta.5

package/INSTALL.md

@@ -749,6 +749,8 @@ 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>`.
@@ -922,12 +924,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/bin/connect.mjs

@@ -45,7 +45,7 @@ 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 { 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";
@@ -555,17 +555,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 +616,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 +667,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 +679,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 +687,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 +734,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

package/bin/disconnect.mjs

@@ -57,7 +57,7 @@ import { stdin, stdout } from "node:process";
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir, userInfo } from "node:os";
-import { CONNECT_CLIENTS, clientById } from "../shared/connect-clients.mjs";
+import { CONNECT_CLIENTS, WHERE_FLAG, clientById, leadRouteFor } from "../shared/connect-clients.mjs";
 import { defaultDenylistPath, disablePlan, revokeEveryonePlan, applyDisablePlan, describeClosure, recordedKeysFor, removeRecordedKeys } from "../shared/client-door.mjs";
 import { loadGrants } from "../shared/scope.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
@@ -83,6 +83,8 @@ async function main() {
     say("  `clearotron grant` manages that.");
     say("");
     say("    --client <name>   which assistant you connected (see --list for the names)");
+    say("    --where here|elsewhere");
+    say("                      how you connected it: on this machine, or over the internet with a key");
     say("    --list            the assistants this build knows");
     say("    --everyone        the admin act: revoke EVERY issued key on this install. It says");
     say("                      how many keys and how many people that is before doing it.");
@@ -90,7 +92,7 @@ async function main() {
     say("");
     return 0;
   }
-  const known = new Set(["--client", "--list", "--dry-run", "--everyone", "--help", "-h"]);
+  const known = new Set(["--client", "--where", "--list", "--dry-run", "--everyone", "--help", "-h"]);
   const unknown = argv.filter((a) => a.startsWith("--") && !known.has(a));
   if (unknown.length) {
     console.error(`disconnect: unrecognised flag(s): ${unknown.join(", ")}`);
@@ -137,18 +139,21 @@ async function main() {
   say(`  ${chosen.name}`);
   say("");
 
-  // The row's own property decides the side. `accepts: "stdio"` never touched this install; "either"
-  // only opens the door when its stdio route was missing, and on THIS box (the one disconnect runs on)
-  // the stdio route resolves, so its connect handed over a command too.
-  if (chosen.accepts === "stdio" || chosen.accepts === "either") {
+  // THE ROUTE DECIDES THE SIDE, not the assistant: every row takes both now. Connected on this machine,
+  // it never touched this install; connected over the internet, it holds a key and the key is what goes.
+  // Unnamed, the route is the one `connect` gives the same id unnamed, so the two verbs pair up.
+  const w = argv.indexOf("--where");
+  if (w >= 0 && !Object.hasOwn(WHERE_FLAG, argv[w + 1] ?? "")) {
+    console.error(`disconnect: --where takes one of: ${Object.keys(WHERE_FLAG).join(", ")}`);
+    process.exit(2);
+  }
+  const route = w >= 0 ? WHERE_FLAG[argv[w + 1]] : (i >= 0 ? leadRouteFor(argv[i + 1]) : chosen.lead);
+  if (route === "disk") {
     say("  Connecting this assistant changed nothing on this install — it runs the software itself,");
     say("  from the configuration you added on its side. To disconnect it, remove that entry in the");
     say("  assistant's own settings.");
-    if (chosen.accepts === "either") {
-      say("");
-      say("  If you connected it by address instead, the door and key are shared — disconnect the");
-      say("  assistant you named when the door was opened, and the closure covers this one too.");
-    }
+    say("");
+    say("  If you connected it over the internet instead, run this again with --where elsewhere.");
     return 0;
   }
 

package/bin/onboard.mjs

@@ -99,7 +99,15 @@ import { entrypointOf } from "../driver/systemd/install-census.mjs";         //
 import { overlayReport, renderOverlayReport } from "../shared/doctrine-overlay.mjs";   // — the doctor reports the overlay
 import { whereSavesGo, storeCommitRefusal, storeInRepo, storeOutsideRepoMessage, resolveStoreRepoRoot } from "../shared/store-in-repo.mjs";   // — doctor says where a portal save goes once it is committed, and why saved searches are off
 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 { probeEngineTurn, probeFailureText, PROBE_TIMEOUT_SEC, engineEnvKeys } from "../driver/engine/probe.mjs";
+
+// THE PROVING SENTENCES NAME NO MODEL. They printed the driver's tier word, which is an Anthropic model's
+// name, on both engines, so a codex user was told setup was about to spend on a model family they do not
+// use. "Its cheapest model" is true of either engine and brands neither.
+export const probingLine = (engineId) =>
+  `Probing ${engineId} with one turn on its cheapest model (this SPENDS; ${PROBE_TIMEOUT_SEC}s ceiling)…`;
+export const proveQuestion = ({ engineId, lane }) =>
+  `Prove ${engineId} on the ${lane} lane now with one turn on its cheapest model (a few tokens, ${PROBE_TIMEOUT_SEC}s ceiling)?`;
 import { runRequiredNames, missingRequirements, REGISTER_ENV, ENGINE_ENV } from "../driver/run-requirements.mjs";   // the order-time gate's own question, asked here rather than restated
 import { pinEnv, envFrom } from "../shared/env-aliases.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -1206,7 +1214,7 @@ export async function runCheck() {
   // deliberate — a second reader would drift from this one exactly as the composer and the checker did
   // in F41, and the drift is invisible because both sides keep passing their own arms.
   const unitDir = join(homedir(), ".config", "systemd", "user");
-  const { BACKGROUND_UNITS } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
+  const { BACKGROUND_UNITS, startPaths } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
   const hosted = BACKGROUND_UNITS.some((u) => existsSync(join(unitDir, u)));
   const unitEnv = hosted
     ? unitEnvironment({
@@ -1440,7 +1448,7 @@ export async function runCheck() {
     } else if (!bin.executable || bin.relative) {
       info("not probed — there is no usable binary to probe. Fix the line above first.");
     } else {
-      say(`\n  Probing ${engineId} with one ${PROBE_MODEL}-tier turn (this SPENDS; ${PROBE_TIMEOUT_SEC}s ceiling)…`);
+      say(`\n  ${probingLine(engineId)}`);
       // The engine as a RUN would see it: environment first, .env behind it. Only the engine-selection
       // keys — the probe must bill exactly the way this box bills and moves no other variable.
       const probeEnv = { ...process.env };
@@ -1628,6 +1636,13 @@ export async function runCheck() {
         // because a reader debugging `clearotron run` by hand IS this process.
         info(`this command's own process ${where} — a CLI is not started by the units' EnvironmentFile, so `
           + "that differs by design and is not what a run uses");
+      } else if (!hosted && svcCustomers?.from === serviceEnvLabel) {
+        // NAMED IN THE ENV FILE ALONE, ON AN INSTALL WITH NO UNITS. `clearotron start` loads that file and
+        // its services inherit the store; this command does not load it, so its own process fell back to
+        // the bundled roster and printed that as the answer, one line below a ✓ for the same variable.
+        ok(`the services resolve profiles from ${svcCustomers.v} (${svcCustomers.from})`);
+        info(`this command's own process ${where} — it does not load ${serviceEnvFile}, so that differs by `
+          + `design and is not what \`${invoke("start")}\` hands the services`);
       } else {
         if (r.situation === "overlay" && !r.findings.length) ok(`${where} — the configured store`);
         else if (r.situation === "bundled-fallback") info(`${where} — THE BUNDLED DEMO ROSTER, because CLEAROTRON_CUSTOMERS_DIR is unset. Legitimate on a generic-defaults install; a fallback either way, and it is what a misconfigured deployment also looks like`);
@@ -1638,7 +1653,8 @@ export async function runCheck() {
         info(`the units are installed but their environment could not be read (${unitEnv?.why ?? "no reason given"}) — `
           + "what the services resolve is not judged here, and the line above is this process's own answer");
       info("what a RUN used is its own `profile-store` journal line — this command reports what the "
-        + (hosted ? "units' file says, which the running services read at their own start" : "environment you are typing in says"));
+        + (hosted ? "units' file says, which the running services read at their own start"
+          : `environment you are typing in and your environment file say, which \`${invoke("start")}\` reads at its own start`));
       // ── AND WHO IS ACTUALLY IN IT ─────────────────────────────────────────
       //
       // The line above names the STORE. An operator who has just configured one wants to know their
@@ -1807,16 +1823,32 @@ export async function runCheck() {
   // be read, the lines above already said so and nothing is judged here. A store that is configured but
   // holds a file that cannot be read fails every company's saved searches, in the portal and the
   // connector alike, so that is read here too.
+  //
+  // WITH NO UNITS, THE SERVICES ARE `clearotron start`'s CHILDREN, and it hands every one of them a store
+  // whether or not the env file names it. So "off" is only ever true of a hosted box. This read the env
+  // file alone, and on a local install started before `start` wrote the store there, it told a portal
+  // that was listing saved searches that they were off.
   if (!hosted || serviceKnown) {
-    const recipesSet = hosted ? effectiveForService("CLEAROTRON_RECIPES_DIR") : effective("CLEAROTRON_RECIPES_DIR");
+    // Layered as effectiveForService layers it — this command's environment over the services' file — so
+    // the repository root is read from the same place the store directory is.
+    let storeEnv = { ...(serviceFileEnv ?? {}), ...process.env };
+    let recipesSet = effectiveForService("CLEAROTRON_RECIPES_DIR");
+    let handedBy = "";
+    if (!hosted && !recipesSet?.v) {
+      const handed = startPaths({ env: storeEnv });
+      recipesSet = { v: handed.recipes, from: "clearotron start", name: "CLEAROTRON_RECIPES_DIR" };
+      storeEnv = { ...storeEnv, RECIPE_REPO_ROOT: handed.configStore };
+      handedBy = ` — where \`${invoke("start")}\` puts them`;
+    }
     const recipesDir = recipesSet?.v || null;
     if (!recipesDir) {
       info("saved searches are off: CLEAROTRON_RECIPES_DIR is not set, so Custom searches in the portal and the "
         + "connector offer none. Name a directory inside a git repository to switch them on");
+    } else if (handedBy && !existsSync(join(storeEnv.RECIPE_REPO_ROOT, ".git"))) {
+      // NOT CREATED YET IS NOT UNREADABLE. The store does not exist until the first start makes it, and
+      // reading it now would report a missing directory as a broken one.
+      info(`saved searches switch on at the first \`${invoke("start")}\`, which creates their store in ${recipesDir}`);
     } else {
-      // Layered as effectiveForService layers it — this command's environment over the services' file — so
-      // the repository root is read from the same place the store directory above was.
-      const storeEnv = { ...(serviceFileEnv ?? {}), ...process.env };
       const resolved = resolveStoreRepoRoot({ names: ["RECIPE_REPO_ROOT", "PROFILE_REPO_ROOT"], fallback: REPO, env: storeEnv });
       const reach = storeInRepo(recipesDir, resolved.root);
       if (!reach.ok) {
@@ -1829,7 +1861,7 @@ export async function runCheck() {
         if (unreadable) {
           warn(`saved searches cannot be read from ${recipesDir}: ${unreadable}. Every company's saved searches fail `
             + "to load, in the portal and the connector, until that file is fixed");
-        } else ok(`saved searches are read from ${recipesDir}, and saves are committed in ${reach.repo}`);
+        } else ok(`saved searches are read from ${recipesDir}${handedBy}, and saves are committed in ${reach.repo}`);
       }
     }
   }
@@ -3281,7 +3313,7 @@ try {
     // skipping it costs an hour later.
     info("A file that exists is not an engine that works — so setup tries one before writing anything.");
     info("It takes a few seconds here. Skipped, a broken engine surfaces an hour into a real search.");
-    if (!await confirm(`Prove ${pick.id} on the ${authPick.id} lane now with one ${PROBE_MODEL}-tier turn (a few tokens, ${PROBE_TIMEOUT_SEC}s ceiling)?`, true)) {
+    if (!await confirm(proveQuestion({ engineId: pick.id, lane: authPick.id }), true)) {
       info("Not proven, so not written. Pick again — the last row configures no engine at all.");
       continue;
     }

package/bin/start.mjs

@@ -355,6 +355,50 @@ export function defaultGrantsPath({ env = process.env, demo = false } = {}) {
   return installPaths(join(homedir(), demo ? "trademark-demo" : "trademark")).grants;
 }
 
+/**
+ * The paths `clearotron start` hands its services: the install's layout under `base`, with whatever the
+ * environment already names winning over the layout's default, as `start` has always applied it.
+ *
+ * EXPORTED FOR THE ONE OTHER READER THAT MUST AGREE WITH IT. On an install with no background units,
+ * `clearotron doctor` has no unit file to read the services' environment from: the services are this
+ * command's children and get the saved-search store from here. An install started before the store was
+ * written to the env file has no line there to read, so doctor asks this function for it, and the
+ * answer it prints and the one the services were given have one author.
+ *
+ * NOT IN A DEMO. Nothing the environment says about an install is the demo's: with the reader's settings
+ * in force, 0.3.0-beta.1's demo seeded its example reports into their real archive.
+ */
+export function startPaths({ env = process.env, base = join(homedir(), "trademark"), demo = false } = {}) {
+  const paths = installPaths(base);
+  if (demo) return paths;
+  for (const [k, name] of [["pool", "CLEAROTRON_REPORTS_DIR"], ["workspace", "CLEAROTRON_WORK_DIR"], ["queue", "CLEAROTRON_QUEUE_DIR"],
+    ["outbox", "CLEAROTRON_OUTBOX_DIR"], ["locks", "CLEAROTRON_RUN_LOCK_DIR"], ["grants", "CLEAROTRON_ACCESS_FILE"],
+    ["recipes", "CLEAROTRON_RECIPES_DIR"]]) if (env[name]) paths[k] = env[name];
+  if (env.RECIPE_REPO_ROOT) paths.configStore = env.RECIPE_REPO_ROOT;
+  if (env.PORTAL_AUDIT) paths.audit = env.PORTAL_AUDIT;
+  return paths;
+}
+
+/**
+ * The saved-search store, as the env file must record it for every reader OUTSIDE this command's tree.
+ *
+ * The services are handed the store by `childEnv`. A connector an assistant launches, `clearotron doctor`
+ * and every other hand-run command are not this command's children: they read the env file, and the
+ * file never named the store. So on a local install the portal listed a company's saved searches, the
+ * connected assistant was told there were none, and doctor said saved searches were off. Written
+ * add-only beside the secrets, as `npx clearotron install` writes the reports and work directories: a
+ * line an operator wrote wins.
+ */
+export function storesForOtherReaders(paths) {
+  return { CLEAROTRON_RECIPES_DIR: paths.recipes, RECIPE_REPO_ROOT: paths.configStore };
+}
+
+// Written above each line, so a reader who moves the install sees that these two move with it.
+const STORE_NOTES = {
+  CLEAROTRON_RECIPES_DIR: "Where saved searches are kept. `clearotron start` created it; edit both lines if you move the install.",
+  RECIPE_REPO_ROOT: "The git repository saved searches are committed in, which holds the directory above.",
+};
+
 /** Everything this install keeps on disk, under one base directory. */
 export function installPaths(base) {
   return {
@@ -846,20 +890,11 @@ if (isMain) {
   const DEMO = argv.includes("--demo");
   // The same base `npm run setup` writes under, so whichever of the two a reader ran first, the other
   // finds the same install rather than a second one beside it.
-  const paths = installPaths(flag("--base", join(homedir(), DEMO ? "trademark-demo" : "trademark")));
   // Whatever the environment already says wins over the base-derived default, for every path — a reader
-  // who ran `npm run setup` has these in .env already and this must not move their data.
-  //
-  // NOT IN A DEMO. Nothing the environment says about an install is the demo's: with the reader's
-  // settings in force, 0.3.0-beta.1's demo seeded its example reports into their real archive. Not read,
-  // rather than deleted from the environment, so a real start cannot be reached by this branch at all.
-  if (!DEMO) {
-    for (const [k, name] of [["pool", "CLEAROTRON_REPORTS_DIR"], ["workspace", "CLEAROTRON_WORK_DIR"], ["queue", "CLEAROTRON_QUEUE_DIR"],
-      ["outbox", "CLEAROTRON_OUTBOX_DIR"], ["locks", "CLEAROTRON_RUN_LOCK_DIR"], ["grants", "CLEAROTRON_ACCESS_FILE"],
-      ["recipes", "CLEAROTRON_RECIPES_DIR"]]) if (process.env[name]) paths[k] = process.env[name];
-    if (process.env.RECIPE_REPO_ROOT) paths.configStore = process.env.RECIPE_REPO_ROOT;
-    if (process.env.PORTAL_AUDIT) paths.audit = process.env.PORTAL_AUDIT;
-  }
+  // who ran `npm run setup` has these in .env already and this must not move their data. Not in a demo,
+  // which `startPaths` says why. One author, because `doctor` asks the same function what the services
+  // were handed.
+  const paths = startPaths({ env: process.env, base: flag("--base", join(homedir(), DEMO ? "trademark-demo" : "trademark")), demo: DEMO });
   // ── THIS INSTALL'S FIRST START, read before this start writes either file that answers it ────────────
   //
   // The grants file and the config store's repository are both written further down, on every start
@@ -1117,14 +1152,19 @@ if (isMain) {
   const portalSecret = secretFor("PORTAL_SECRET");
   const tokenSecret = secretFor("TRADEMARK_MCP_TOKEN_SECRET");
   if (!process.env.PORTAL_LOCAL_USER) generated.PORTAL_LOCAL_USER = user;
+  const stores = DEMO ? {} : storesForOtherReaders(paths);
 
   // A DEMO WRITES NO SECRETS AND NO ADDRESS. They are generated per run and live in memory only, which
   // is the same posture the ops key already has here — and it is what makes "removing the demo is one
   // directory" true rather than nearly true.
-  if (Object.keys(generated).length && !DEMO) {
+  //
+  // THE STORES ARE WRITTEN EVEN WHEN NO SECRET IS. An install whose secrets are already in the file is
+  // exactly the install whose connector and doctor could not see its saved searches, and a gate on the
+  // secrets alone would never reach it.
+  if ((Object.keys(generated).length || Object.keys(stores).length) && !DEMO) {
     let existing = "";
     try { existing = readFileSync(ENV_PATH, "utf8"); } catch (e) { if (e.code !== "ENOENT") fatal(`${ENV_PATH} exists but could not be read (${e.code}).`); }
-    const merged = mergeEnvFile(existing, generated);
+    const merged = mergeEnvFile(existing, { ...generated, ...stores }, { notes: STORE_NOTES });
     if (merged.added.length) {
       // ONE WRITER FOR EVERY FILE THAT HOLDS CREDENTIALS, and it creates the directory. This site had its
       // own copy of the write and did not learn what the wizard's copy learned when `.env` moved under
@@ -1135,7 +1175,7 @@ if (isMain) {
       } catch (e) {
         fatal(`could not write ${ENV_PATH} (${String(e?.message ?? e)}).`);
       }
-      // NAMES only. This file is where the credentials are.
+      // NAMES only. Some of what this file holds is credentials.
       say(`  wrote          ${merged.added.join(", ")} to ${ENV_PATH} (mode 600)`);
     }
   }

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "5c5342ab541f8240732467dfc8bbf3c065ef13f6",
-  "version": "0.3.0-beta.3"
+  "commit": "a9ac3366ee814b9faf6a5d23fe7d0c8f3a5c0d3f",
+  "version": "0.3.0-beta.5"
 }

package/driver/CHANGELOG.md

@@ -1,5 +1,30 @@
 # clearotron-driver
 
+## 0.3.0-beta.5
+
+### Patch Changes
+
+- 5f7e295: Fixed: A Clearotron install signed in to OpenAI's `codex` with a subscription keeps working after codex refreshes its login. Before, every search after the first refresh failed within seconds until you signed in again.
+- 2878809: Fixed: When the company store cannot record a new company, the New company page now says why and what fixes it, instead of "Try again shortly". Someone who does not run the installation is told to ask whoever does.
+- e7cd9e1: Fixed: On an install run with `clearotron start`, a connected assistant now lists the same saved searches as the portal, including Generic's. `clearotron doctor` no longer says working saved searches are off, and it names one place profiles come from.
+- e7cd9e1: Fixed: When setup offers to try your engine, it no longer names an Anthropic model to someone who chose OpenAI's `codex`.
+
+## 0.3.0-beta.4
+
+### Minor Changes
+
+- a9f5375: New: Use your own AI asks first where Clearotron is running, then shows the steps for your app beside the list. The same five apps are offered either way.
+  
+  New: Claude Code and Codex can connect to an installation running elsewhere, and the ChatGPT desktop app to one on the same machine.
+  
+  Fixed: Codex was told to paste a settings block into a terminal. Its steps now name the file the block goes in.
+  
+  For operators: `clearotron connect` and `clearotron disconnect` take `--where here` or `--where elsewhere`. Assistant names used before, such as `cowork`, still work.
+
+### Patch Changes
+
+- a9f5375: New: the company switcher in the sidebar ends with `+ New company`. Making a company is now one click from every screen, whether or not a company is selected.
+
 ## 0.3.0-beta.3
 
 ### Patch Changes
@@ -7,9 +32,9 @@
 - a782aad: Fixed: Creating a company is refused, with nothing left behind, when the configuration store cannot record it. The company used to be created anyway, with no record of who made it or when, and its organisation was given access to it.
   
   A store with no git identity is the usual cause on a new machine, and the refusal names the command that fixes it. Setup and `clearotron start` now check a store they adopt for this straight away.
-- d1ef225: Fixed: A stage stopped at its time limit now records the output it actually produced. It used to record a small fraction, so a stage that was working read as one that had stalled.
+- d1ef225: Fixed: A search step stopped at its time limit now records the output it actually produced. It used to record a small fraction, so a step that was working read as one that had stalled.
   
-  The token totals `clearotron tokens` reports for runs with a stopped stage now include that output.
+  The token totals `clearotron tokens` reports for runs with a stopped step now include that output.
 - 0ff42d1: Fixed: `clearotron doctor` now says when saved searches are switched off and why, and when a saved search file cannot be read.
   
   An assistant asking for saved searches is told when they could not be read, instead of being told there are none.
@@ -63,11 +88,11 @@
   
   Fixed: A search now records any of your default territories that the engine cannot search, in the record of that search. A mistyped default no longer narrows a search silently.
 - eacfce4: Fixed: An assistant connected to a local install now sees the saved searches the portal shows, and can plan a run from one of them. Before, outside the demo, only the portal was told where saved searches are kept, so an assistant was told the install had none.
-- 34cc1c7: For operators: A health check that could not look now fails instead of reporting success. Two halves of the unit check can go quiet. One goes quiet when the installation does not say which installation it is; the other when the walk over the unit files does not finish. Both used to note that they had not run and then pass.
+- 34cc1c7: For operators: A deployment health check that could not finish now fails instead of reporting success. Two parts of the service check could skip themselves. One skipped when the installation did not say which installation it is; the other when the scan of the service files did not finish. Both used to note that they had not run and then pass.
   
   For operators: Set `CLEAROTRON_BOX` to `prod` or `test`. Those are the only two values the check accepts; anything else, including any other name, reads as unnamed and fails. The failure names the setting and says what went unchecked.
   
-  For operators: The half that goes quiet is the one that notices a service that has stopped and stayed stopped. The other half lists what is running, so it cannot see something that is no longer there. While that half is suppressed, a service can disappear without the check saying anything.
+  For operators: The part that could skip itself is the one that notices a service that has stopped and stayed stopped. The other part lists what is running, so it cannot see something that is no longer there. While the first part is skipped, a service can disappear without the check saying anything.
 - b45a5cf: Fixed: `clearotron doctor` now reports everything a search would be refused for, checked against the environment the search will run in. So an installation it passes is one that can run a search.
   
   Fixed: A token set in the installation's own configuration file now reaches the engine check. A headless server set up the documented way proves its engine instead of reporting it signed out.
@@ -112,7 +137,7 @@
   Fixed: When a feature is switched off on your installation, the screen says so and what to change. It used to suggest trying again shortly.
   
   Fixed: The link to the risk-framework guide opens in a new tab and goes straight to the section on writing your own. It also appears on the Company profile screen.
-- ad088d6: Fixed: The audit workbook's "What was searched" sheet is now in plain words. Its Result and Note columns carry the search log's own notes. Engine vocabulary could reach them: a receipt "deferred", a full web address, a bare HTTP code. Those words are now replaced as the workbook is built, a republished report included. A search recorded as not run still reads as not searched. Search terms and names stay exactly as written, because they record what was searched.
+- ad088d6: Fixed: The audit workbook's "What was searched" sheet is now in plain words. Its Result and Note columns carry the search log's own notes. Internal terms could reach them: a status such as "deferred", a full web address, a bare HTTP code. Those words are now replaced as the workbook is built, a republished report included. A search recorded as not run still reads as not searched. Search terms and names stay exactly as written, because they record what was searched.
 - ff16a3b: For operators: The deployment health check now reports whether the component that updates an installation is itself up to date. It was the one part of a deployment the check could not identify. An installation kept current by an out-of-date updater could report healthy while serving stale code.
   
   For operators: An updater that cannot be identified is now reported as a failure rather than passed over. A copy old enough to predate this reporting writes nothing at all. That silence is the case worth knowing about, so it is treated as a finding.
@@ -142,7 +167,7 @@
   
   The product now says company throughout. It used to say brand owner, account, client and customer for the same thing. The firm running the installation is named separately, in the top bar.
   
-  Companies created through the settings page were saved without a risk framework. Their matters were then rated under the house default, with nothing on screen saying so. Every company created now carries one, and says which.
+  Companies created through the settings page were saved without a risk framework. Their matters were then rated under the default risk framework, with nothing on screen saying so. Every company created now carries one, and says which.
 - f75266d: New: The setup wizard now asks for the organisation's name after the sign-in address, and the person who installs starts with access to everything.
   
   `clearotron grant add` sets a person's two permissions with `--run` and `--manage`; with neither, the person can look and start nothing.
@@ -164,18 +189,18 @@
   
   Getting the deck's shape wrong used to fail quietly. The profile screen showed the framework's title and your band colours, and silently omitted the box saying what the bands mean. The new command answers that question directly, using the screen's own read of the deck.
   
-  Fixed: a framework served from the product's own files, while you have a configuration store set, now says so.
+  Fixed: When you have a configuration store set and a risk framework comes from the product's own files instead, the product now says so.
   
   Your store is looked in first, and the product's files answer when it is silent. The product ships decks under names you may also have chosen. So a deck that went missing from your store was replaced by ours rather than reported absent. Same band words, different rubric, nothing raised anywhere. The profile screen now writes one line naming what happened, and the new command reports it.
   
-  Fixed: the house triage ladder's profile page explains its bands again.
+  Fixed: The built-in triage framework's profile page explains its bands again.
   
   Its band sections stated their meanings as plain paragraphs, which the screen does not read. Every company without a framework of its own saw band colours and no explanation. The wording is unchanged.
-- cfb9a9f: Fixed: `clearotron doctor` now says which companies your portal's trigger key can start.
+- cfb9a9f: Fixed: `clearotron doctor` now lists the companies your portal's key may start runs for.
   
   The key carries a list of the companies it may start runs for. A company added after the key was minted is outside it. Doctor reported the key's expiry and never its coverage. So the one command whose job is to tell you what a machine is configured for said nothing about it.
   
-  It reads the roster the services read, not the one a command-line process resolves, and it says which. Those two can disagree, and when they do the difference is the whole answer.
+  It reads the company list the background services read, not the one a command run in a terminal would find, and it says which. The two can differ, and when they do, that difference is the answer.
   
   The line is a note, not a failure. Your portal takes a fresh credential at the start of every call, so a company outside the key is not normally refused. It is refused when the portal cannot take a fresh one, and the line says so and gives you the command to widen the key.
 - ba2899b: Fixed: On reports searched through Signa, each register finding now links to the office's own page for that record, where the office publishes one. Singapore publishes no such page, so its registrations are cited by number, and the report says why. A number that an office's page cannot take is cited the same way.