clearotron 0.3.0-beta.3 → 0.3.0-beta.4

package/INSTALL.md

@@ -922,12 +922,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/build-info.json

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

package/driver/CHANGELOG.md

@@ -1,5 +1,21 @@
 # clearotron-driver
 
+## 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

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.3",
+  "version": "0.3.0-beta.4",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/suite-census.json

@@ -1366,8 +1366,8 @@
           "todos": 0
         },
         "connect-clients-are-data.test.mjs": {
-          "tests": 12,
-          "asserts": 46,
+          "tests": 15,
+          "asserts": 75,
           "skips": 0,
           "todos": 0
         },
@@ -1397,7 +1397,7 @@
         },
         "connector-annotations-and-pack.test.mjs": {
           "tests": 7,
-          "asserts": 11,
+          "asserts": 12,
           "skips": 0,
           "todos": 0
         },
@@ -5774,8 +5774,8 @@
           "todos": 0
         },
         "newCompanyReachableFromProfile.test.ts": {
-          "tests": 3,
-          "asserts": 7,
+          "tests": 5,
+          "asserts": 13,
           "skips": 0,
           "todos": 0
         },
@@ -5913,7 +5913,7 @@
         },
         "useYourAI.test.ts": {
           "tests": 13,
-          "asserts": 46,
+          "asserts": 41,
           "skips": 0,
           "todos": 0
         },

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-artifacts-mcp
 
+## 0.3.0-beta.4
+
+No changes in this release.
+
 ## 0.3.0-beta.3
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.3",
+  "version": "0.3.0-beta.4",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.3.0-beta.3",
+  "version": "0.3.0-beta.4",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",