clearotron 0.4.0 → 0.4.1-beta.1

package/scripts/mcp-registry-listing.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// mcp-registry-listing.mjs — the MCP Registry lists each stable release npm serves, and nothing else.
+//
+//   node scripts/mcp-registry-listing.mjs plan                  the stables npm serves that the registry does not list
+//   node scripts/mcp-registry-listing.mjs publish <publisher>   list each of them, oldest first, and read each back
+//
+// The registry (registry.modelcontextprotocol.io) is where MCP clients look a server up. It holds metadata
+// only, about a package npm already serves, and a version's metadata can never change once it is listed.
+// So nothing here reacts to a release: it asks npm which stables it serves and the registry which it
+// lists, and lists what is missing. A run that fails is asked again by the next one, and no release ever
+// waits for this.
+//
+// ONE SOURCE SETS BOTH VERSIONS. Every field that names a version comes from npm's manifest for that exact
+// version, and so does the name: `mcpName` there is the listing's name. The registry reads `mcpName` from
+// npm in turn and refuses a listing that disagrees, so the two cannot drift.
+//
+// A STABLE WITHOUT `mcpName`. The stables published before the field existed are passed by. One published
+// after the first stable that carries it is refused: something stripped it, and listing past it would hide
+// that.
+//
+// A SOURCE THAT CANNOT BE READ IS EXIT 2, never "nothing to list" and never "already listed". The
+// registry's 404 for this exact name is an answer: nothing is listed under it yet.
+//
+// The registry marks the highest version latest whatever order versions arrive in (`registry_service.go`
+// at v1.8.1). Missing stables are listed oldest first all the same, so its record reads in release order.
+//
+// Exit 0: nothing to list, or each one listed and read back.
+// Exit 1: a stable after the first carrying `mcpName` lacks it, or a listing failed or did not read back.
+// Exit 2: could not look.
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+export const SERVER_NAME = "io.github.CordilleraSarl/clearotron";
+/** The README banner's alt text, a shipped line. The registry allows 100 characters. */
+export const DESCRIPTION = "Clearotron — trademark clearance that shows its work";
+export const SCHEMA = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
+export const REPOSITORY = Object.freeze({ url: "https://github.com/CordilleraSarl/clearotron", source: "github" });
+export const NPM_URL = "https://registry.npmjs.org/clearotron";
+export const LISTED_URL = `https://registry.modelcontextprotocol.io/v0.1/servers/${encodeURIComponent(SERVER_NAME)}/versions`;
+/** The registry's refusal of a version it already holds (`ErrInvalidVersion`, v1.8.1): already listed. */
+const DUPLICATE = /cannot publish duplicate version/;
+
+export class CouldNotLook extends Error {}
+
+const STABLE = /^(\d+)\.(\d+)\.(\d+)$/;
+export const isStable = (v) => STABLE.test(v);
+const parts = (v) => v.match(STABLE).slice(1).map(Number);
+export function compareStable(a, b) {
+  const [x, y] = [parts(a), parts(b)];
+  return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
+}
+
+/** The listing for one stable npm serves, every field that can come from its manifest taken from it. PURE. */
+export function serverJsonFor(manifest) {
+  if (manifest?.mcpName !== SERVER_NAME) {
+    throw new Error(`${manifest?.name}@${manifest?.version} carries mcpName ${JSON.stringify(manifest?.mcpName ?? null)}, not ${SERVER_NAME}`);
+  }
+  if (!isStable(manifest.version)) throw new Error(`${manifest.version} is not a stable version`);
+  return {
+    $schema: SCHEMA,
+    name: manifest.mcpName,
+    description: DESCRIPTION,
+    repository: { ...REPOSITORY },
+    version: manifest.version,
+    packages: [{
+      registryType: "npm",
+      identifier: manifest.name,
+      version: manifest.version,
+      transport: { type: "stdio" },
+      packageArguments: [{ type: "positional", value: "mcp" }],
+    }],
+  };
+}
+
+/**
+ * Which stables to list. PURE.
+ * @param {Record<string, object>} served  npm's manifests, by version
+ * @param {Set<string>} listed             the versions the registry lists under the name
+ * @returns {{ list: object[], passedBy: string[], refused: string[] }}  `list` oldest first
+ */
+export function plan(served, listed) {
+  const stables = Object.keys(served).filter(isStable).sort(compareStable);
+  const first = stables.findIndex((v) => served[v]?.mcpName === SERVER_NAME);
+  if (first === -1) return { list: [], passedBy: stables, refused: [] };
+  const list = [];
+  const refused = [];
+  for (const v of stables.slice(first)) {
+    if (served[v]?.mcpName !== SERVER_NAME) refused.push(v);
+    else if (!listed.has(v)) list.push(served[v]);
+  }
+  return { list, passedBy: stables.slice(0, first), refused };
+}
+
+async function readJson(url, fetchImpl, who) {
+  let res;
+  try {
+    res = await fetchImpl(url, { headers: { accept: "application/json" } });
+  } catch (e) {
+    throw new CouldNotLook(`${who} did not answer: ${e.message}`);
+  }
+  if (res.status === 404) return null;
+  if (res.status !== 200) throw new CouldNotLook(`${who} answered ${res.status}`);
+  try {
+    return await res.json();
+  } catch {
+    throw new CouldNotLook(`${who} answered with something that is not JSON`);
+  }
+}
+
+/** npm's manifests for every version it serves. */
+export async function readServed(fetchImpl = fetch) {
+  const body = await readJson(NPM_URL, fetchImpl, "npm");
+  if (!body?.versions || typeof body.versions !== "object") throw new CouldNotLook("npm's answer names no versions");
+  return body.versions;
+}
+
+/** The versions the registry lists under the exact name: empty when it has never listed it. */
+export async function readListed(fetchImpl = fetch) {
+  const body = await readJson(LISTED_URL, fetchImpl, "the MCP Registry");
+  if (body === null) return new Set();
+  if (!Array.isArray(body?.servers)) throw new CouldNotLook("the MCP Registry's answer lists no servers");
+  if (body.metadata?.nextCursor) throw new CouldNotLook("the MCP Registry's answer is paged, and this reads one page");
+  const listed = new Set();
+  for (const s of body.servers) {
+    if (s?.server?.name !== SERVER_NAME) throw new CouldNotLook(`the MCP Registry answered for ${JSON.stringify(s?.server?.name)}`);
+    listed.add(s.server.version);
+  }
+  return listed;
+}
+
+/** Hand one listing to the publisher. A refusal as a duplicate means it is already there. */
+export function publishOne(manifest, publisher, run = spawnSync) {
+  const dir = mkdtempSync(join(tmpdir(), "mcp-registry-"));
+  try {
+    const file = join(dir, "server.json");
+    writeFileSync(file, JSON.stringify(serverJsonFor(manifest), null, 2) + "\n");
+    const r = run(publisher, ["publish", file], { encoding: "utf8" });
+    const said = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+    if (r.status === 0) return { ok: true, said };
+    if (DUPLICATE.test(said)) return { ok: true, duplicate: true, said };
+    return { ok: false, said: said || String(r.error?.message ?? `exit ${r.status}`) };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function main(argv, { fetchImpl = fetch, run = spawnSync, output = process.env.GITHUB_OUTPUT, log = console.log, warn = console.error } = {}) {
+  const [cmd, publisher] = argv;
+  if (!(cmd === "plan" || (cmd === "publish" && publisher))) {
+    warn("usage: mcp-registry-listing.mjs plan | publish <publisher>");
+    return 2;
+  }
+  let p;
+  try {
+    p = plan(await readServed(fetchImpl), await readListed(fetchImpl));
+  } catch (e) {
+    if (!(e instanceof CouldNotLook)) throw e;
+    warn(`mcp-registry: could not look: ${e.message}`);
+    return 2;
+  }
+  if (p.passedBy.length) log(`mcp-registry: passed by, published before mcpName: ${p.passedBy.join(", ")}`);
+  if (p.refused.length) {
+    warn(`mcp-registry: REFUSED. These stables came after the first that carries mcpName and do not carry it: ${p.refused.join(", ")}`);
+    return 1;
+  }
+  log(p.list.length ? `mcp-registry: to list, oldest first: ${p.list.map((m) => m.version).join(", ")}` : "mcp-registry: nothing to list");
+  if (output) appendFileSync(output, `count=${p.list.length}\n`);
+  if (cmd === "plan") return 0;
+
+  for (const manifest of p.list) {
+    const r = publishOne(manifest, publisher, run);
+    if (!r.ok) {
+      warn(`mcp-registry: ${manifest.version} was not listed: ${r.said}`);
+      return 1;
+    }
+    let listed;
+    try {
+      listed = await readListed(fetchImpl);
+    } catch (e) {
+      if (!(e instanceof CouldNotLook)) throw e;
+      warn(`mcp-registry: could not read ${manifest.version} back: ${e.message}`);
+      return 2;
+    }
+    if (!listed.has(manifest.version)) {
+      warn(`mcp-registry: the publisher ${r.duplicate ? "called" : "reported"} ${manifest.version} ${r.duplicate ? "a duplicate" : "listed"}, and the registry does not list it`);
+      return 1;
+    }
+    log(`mcp-registry: ${manifest.version} ${r.duplicate ? "was already listed" : "listed"}, and read back`);
+  }
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/scripts/mint-plugin-folder.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// mint-plugin-folder.mjs — the folder Claude's plugin directory installs, its copies derived from the tree.
+//
+// The directory installs one folder, never the repository: a person who installs the plugin gets
+// `plugin/` and nothing else. What the folder needs from the tree is copied into it, and `--check`
+// refuses a folder whose copies have drifted from their sources:
+//   - the three connector skills, byte for byte from `skills/`, which stays the one copy the server
+//     briefs from and the published package ships;
+//   - the licence and its additional terms, byte for byte from the root.
+// Written by hand and not derived: `plugin/README.md`, the manifest, `plugin/scripts/npx.mjs`, the
+// launcher that starts npx on every platform, and `plugin/.mcp.json`, which names the exact stable
+// version the server is started from. A stable cut moves that version and the manifest's together;
+// between stables the package is a beta and the folder still names the last stable.
+//
+//   node scripts/mint-plugin-folder.mjs           write the copies
+//   node scripts/mint-plugin-folder.mjs --check   exit 1 if any copy differs from its source, naming it
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const PLUGIN_DIR = "plugin";
+export const CONNECTOR_SKILLS = Object.freeze(["clearotron-client", "clearotron-account", "clearotron-ops"]);
+
+/** Every copied file of the folder: its path under the root, and its exact bytes. PURE but for reads. */
+export function pluginCopies(root = ROOT) {
+  const read = (p) => readFileSync(join(root, p), "utf8");
+  const out = [];
+  for (const skill of CONNECTOR_SKILLS) {
+    for (const f of readdirSync(join(root, "skills", skill)).sort()) {
+      out.push({ path: join(PLUGIN_DIR, "skills", skill, f), text: read(join("skills", skill, f)) });
+    }
+  }
+  out.push({ path: join(PLUGIN_DIR, "LICENSE"), text: read("LICENSE") });
+  out.push({ path: join(PLUGIN_DIR, "ADDITIONAL-TERMS.md"), text: read("ADDITIONAL-TERMS.md") });
+  return out;
+}
+
+function main(argv) {
+  const check = argv.includes("--check");
+  const stale = [];
+  for (const { path, text } of pluginCopies()) {
+    const at = join(ROOT, path);
+    const now = existsSync(at) ? readFileSync(at, "utf8") : null;
+    if (now === text) continue;
+    if (check) { stale.push(path); continue; }
+    mkdirSync(dirname(at), { recursive: true });
+    writeFileSync(at, text);
+    console.log(`plugin-folder: wrote ${relative(ROOT, at)}`);
+  }
+  if (check && stale.length) {
+    console.error(`plugin-folder: STALE. ${stale.length} copied file(s) differ from their sources:`);
+    for (const p of stale) console.error(`  ${p}`);
+    console.error("Re-mint: node scripts/mint-plugin-folder.mjs");
+    return 1;
+  }
+  if (check) console.log("plugin-folder: current");
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/scripts/release-version.mjs

@@ -42,6 +42,35 @@ export function alreadyOut({ version, tags = [], published = false }) {
   return where;
 }
 
+// ── THE PLUGIN FOLDER FOLLOWS A STABLE, AND ONLY A STABLE ─────────────────────────────────────────────
+//
+// `plugin/` is what Claude's plugin directory installs, and it starts the server from npm at one exact
+// version: the one `"clearotron@X.Y.Z"` argument in its `.mcp.json`, beside the same number in its
+// manifest. A stable cut moves both in the version commit. A beta moves neither, so between stables the
+// folder names the last stable. The pin is found by its prefix, never by its place in the argument list,
+// and a file without exactly one match refuses the cut before anything is stamped.
+export const PLUGIN_SERVER = join("plugin", ".mcp.json");
+export const PLUGIN_MANIFEST = join("plugin", ".claude-plugin", "plugin.json");
+const PIN = /"clearotron@[^"]*"/g;
+const MANIFEST_VERSION = /^ {2}"version": "[^"]*"/gm;
+export const isStableVersion = (v) => /^\d+\.\d+\.\d+$/.test(v);
+
+/** PURE. Both plugin files at `version`, or why they cannot be moved. Nothing else in either changes. */
+export function pluginAtVersion({ server, manifest }, version) {
+  const pins = server.match(PIN) ?? [];
+  if (pins.length !== 1) return { refused: `${PLUGIN_SERVER} carries ${pins.length} "clearotron@" arguments, not one` };
+  const versions = manifest.match(MANIFEST_VERSION) ?? [];
+  if (versions.length !== 1) return { refused: `${PLUGIN_MANIFEST} carries ${versions.length} top-level versions, not one` };
+  const next = {
+    server: server.replace(PIN, `"clearotron@${version}"`),
+    manifest: manifest.replace(MANIFEST_VERSION, `  "version": "${version}"`),
+  };
+  for (const [file, text] of [[PLUGIN_SERVER, next.server], [PLUGIN_MANIFEST, next.manifest]]) {
+    try { JSON.parse(text); } catch (e) { return { refused: `${file} is not JSON after the move: ${e.message}` }; }
+  }
+  return next;
+}
+
 // ── THE CHANNEL DECIDES THE MODE, AND IT HAS TO BE DECIDED HERE ───────────────────────────────────
 //
 // `changeset version` computes a pre-release number or a stable one depending on whether the tree is in
@@ -343,12 +372,27 @@ function main() {
     process.exitCode = 1;
     return;
   }
+  let plugin = null;
+  if (isStableVersion(version)) {
+    const read = (p) => (existsSync(join(ROOT, p)) ? readFileSync(join(ROOT, p), "utf8") : "");
+    plugin = pluginAtVersion({ server: read(PLUGIN_SERVER), manifest: read(PLUGIN_MANIFEST) }, version);
+    if (plugin.refused) {
+      console.error(`release-version: the plugin folder cannot follow ${version}: ${plugin.refused}. Refusing before anything is stamped.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
   const pkgPath = join(ROOT, "package.json");
   const pkg = readJson(pkgPath);
   const was = pkg.version;
   pkg.version = version;
   writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   console.log(`release-version: clearotron ${was} -> ${version} (carried from the fixed group)`);
+  if (plugin) {
+    writeFileSync(join(ROOT, PLUGIN_SERVER), plugin.server);
+    writeFileSync(join(ROOT, PLUGIN_MANIFEST), plugin.manifest);
+    console.log(`release-version: the plugin folder starts clearotron@${version}, and its manifest says ${version}`);
+  }
 
   // AND THE LOCKFILE, WHICH NOTHING ELSE IN THIS CUT TOUCHES. `changeset version` rewrites the
   // workspace manifests and the block above rewrites the root's; `package-lock.json` records the same

package/scripts/score.mjs

@@ -33,7 +33,7 @@
 // ── which directory to point it at ───────────────────────────────────────────────────────────────────
 //
 // The agent WORKSPACE archive dir, never the published pool dir. The pool keeps report.md and
-// findings.json but not `_driver/` or `_records/` — see driver/publish/pool-admin.mjs:145. Without
+// findings.json but not `_driver/` or `_records/` — see doRepublish() in pool-admin.mjs. Without
 // `_driver/` there is no band and no reconciliation, so `withheld` cannot be computed at all, and a
 // scorer that silently reported every withheld mark as `lost` would send every fix to the wrong place.
 // So a run dir with no `_driver/` says so and declines to guess.

package/shared/register-floor.mjs

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// register-floor.mjs — a register's floor, read one way and printed one way, on every path that meets it.
+//
+// A register asked something very broad can answer "at least 10,000" instead of a count: it counted, and
+// gave a floor. That is an answer, never a failure and never a zero (ruled 2026-10-02). The knockout count
+// has printed it as "more than 10,000" since it first met one; the clearance path reads and prints it here
+// with the same words, so the two can never say it two ways.
+
+/** A floor as every page prints it: the register's own figure, and no sentence around it. */
+export const moreThan = (floor) => `more than ${floor.toLocaleString("en-US")}`;
+
+/**
+ * The register's floor on a parsed answer that gave one instead of a count, or null. A floor counts only
+ * with the register's flag AND the number: a flag with no number says no more than "unknown" does. PURE.
+ */
+export function floorOf(parsed) {
+  return parsed?.total_approximate === true && Number.isFinite(parsed?.total_floor) ? parsed.total_floor : null;
+}

package/shared/scope.mjs

@@ -792,6 +792,12 @@ function tenantStamp(scope, asked) {
   throw new Error(`name the organisation whose Generic this is (tenant) — your access covers ${orgs.length}`);
 }
 
+// The install's organisation when the grants file holds exactly one; null with several, none, or no file.
+function soleOrganisation() {
+  const orgs = Object.keys(loadGrants()?.tenants ?? {});
+  return orgs.length === 1 ? orgs[0] : null;
+}
+
 // True iff `email`'s domain (the part after the final '@') is one of firmDomains. PURE (no jose), so the HTTP
 // handler can derive firm-staff-ness from the already-verified CF identity without pulling the auth lib. The
 // `internal` (read-all) grant rests on THIS positive check — NOT on which CF app admitted the caller — so a
@@ -1016,8 +1022,18 @@ export function authorize(scope, toolName, args = {}) {
     // paid run whose delivery packet routes nowhere. A refusal naming the missing field is the cheaper
     // failure by far, and it is not the "accepted then quietly narrower" shape: the preview describes a
     // job stamped from the verified identity, and start_run says plainly which field to add.
-    if (toolName === "plan_run") return stampForwarder(scope, args);
-    return args;
+    //
+    // WHICH ORGANISATION'S GENERIC. An ops token names no person, so there is nobody's reach to read the
+    // organisation from — and passed through bare, every Generic run a connector started was filed under
+    // no organisation, where the Generic filter on Clearances can never find it. On an install that holds
+    // exactly one organisation there is nothing to guess, so the job takes it: the same answer the
+    // person-scoped branch gives a person who sees that one organisation. A named tenant passes as it
+    // stands, and with several organisations (or none) the job is left as it was.
+    const placed = (toolName === "start_run" || toolName === "plan_run") && (args?.profileKey ?? "generic") === "generic"
+      && !(typeof args?.tenant === "string" && args.tenant.trim()) ? soleOrganisation() : null;
+    const routed = placed ? { ...args, tenant: placed } : args;
+    if (toolName === "plan_run") return stampForwarder(scope, routed);
+    return routed;
   }
   // kind === "account": a signed-in CLIENT, across their OWN account(s). Reads the client layer on any of
   // their runs, and drives the run lifecycle for them. Run OWNERSHIP is not checked here — it is enforced

package/shared/trigger-lane.mjs

@@ -228,7 +228,7 @@ export function triggerLaneVerdict({ url = null, hasToken = false, verbs = null,
   // false the moment the door finishes binding, which is seconds later.
   //
   // It is also false as a prediction, and that is the worse half. The submit path makes a FRESH upstream
-  // call per request inside its own try/catch (`driver/portal-service.mjs:1770-1798`) and never consults
+  // call per request inside its own try/catch (the `trigger` call inside makePortalService() in portal-service.mjs) and never consults
   // this verdict. So nothing about a boot-time refusal determines what a clearance does.
   //
   // IT COST A DIAGNOSTIC DETOUR during the 0.1.6 production upgrade, and it prints on every reboot. The

package/skills/clearotron-ops/SKILL.md

@@ -10,28 +10,75 @@ You are an integrator agent driving a trademark clearance engine over MCP. Intak
 call hands the matter to a deterministic pipeline**, and delivery comes back to you as outbox
 events (see `COURIER.md`). You never compose reports and never touch the engine's files.
 
-## Check before you spend — `plan_run`
-
-A search costs real money and takes real time, and the requester usually has not told you which
-search they mean. **`plan_run` takes exactly the same arguments as `start_run`, spends nothing, and
-tells you what would happen**: which product resolves and *where that came from* (their request,
-the account's default, or a saved search), the territories and marketplaces that would actually be
-searched, the turnaround, and any blockers.
-
-Use it whenever the requester has not confirmed the specifics — which is most of the time. Then say
-it back to them in their own terms, with the turnaround the preview reported, and let them answer:
-
-> That would run a **Multi-country focus search** on NOVAPULSE in classes 9 and 41 — your account's
-> default territories (US, EU, JP), back in <the turnaround the preview quoted>. You did not say
-> which search you wanted, so that is the account default rather than something you chose. Shall I
-> run it, or did you want the Knockout search across the whole name list instead?
-
-Two things it is not. It does **not** reserve anything — nothing is held, and nothing expires. And
-it is **advice, not a gate**: `start_run` will still run without it. Getting agreement first is your
-job, not the engine's.
-
-When they confirm, call `start_run` **with the same arguments**. If `plan_run` reported blockers,
-those are questions to put back to the requester — not failures to retry.
+## When a request arrives: confirm it, and start at once
+
+A search costs real money and takes real time. Read the request for everything the search needs, send
+the requester one confirmation, and start the search at once; they correct it afterwards. Never wait for
+a yes.
+
+**1. Is it a new matter?** The matter is the mark, not the thread. A forwarded reply quotes the original
+request beneath it, which makes a follow-up look like a fresh request, so check `list_runs` for the mark
+(in flight and recently delivered) and your own sent confirmation for the thread first. A bare "proceed"
+or a thank-you never starts a second search: reply once that the search is already running, and stop. A
+different mark in the same thread is a distinct matter and its own search. A changed instruction while
+a run is in flight goes in through `feed_context`. Only the requester's explicit "run it again" starts a
+second search of the same mark, with `dupOverride: true`.
+
+**2. Read the brief out of the request.** Ask only for what is both impossible to infer and material.
+- The mark or marks, and what kind each is: a word, a logo, a slogan.
+- The account and the applicant (`profileKey`, `projectKey` and `customer` below). Say the applicant
+  together with what it implies: the applicant's own and affiliated marks are not reported as
+  conflicts. Never guess the applicant from the mark itself.
+- Prior matters on the same reference or project: ask the engine first (`search_runs`, `list_runs`),
+  and say what you found.
+- Goods or classes. Either one suffices: infer the other side, and say that you inferred it
+  ("sparkling water → class 32, inferred").
+- The deadline and every operational instruction (recipients, billing, the reference), each said back
+  with its status: done, will do, or cannot do. Never pass over an instruction in silence.
+- The deliverable as specified (a template, a risk framework, a format), verbatim.
+- How free the client is to change the name, which sets the advice. If the request does not say, state
+  the posture you assumed.
+- Prior and intended use. Unless the request says otherwise, a house root is assumed in use and the new
+  element unused.
+- Special instructions, verbatim.
+
+The reference number and the industry are shown, never asked for.
+
+**3. Check it for free with `plan_run`.** It takes exactly the same arguments as `start_run`, spends
+nothing and holds nothing. It reports which search resolves and where that came from (the request, the
+account's default, or a saved search), the territories and marketplaces that would actually be searched,
+the turnaround, and any blockers, as questions to put back. It is a check, not a gate. Put what it
+reports in the confirmation, above all a search or a scope narrower than the words the requester used.
+
+**4. Send the confirmation in three groups, in this order.**
+- **Corrections and commitments:** a correction to the mark, the deadline diarised, the recipients, the
+  billing, and anything instructed that you will do or cannot do.
+- **Assumed — correct me:** every inferred value with what it does (the applicant and the marks set
+  aside with it, inferred classes, the territories, the use posture), and every default applied. A
+  default fills silence only; it never narrows an explicit instruction, and a stated "worldwide" stays
+  worldwide.
+- **Given:** what the request stated, said back briefly.
+
+End with **"Starting now on this understanding — reply to correct anything."**, and call `start_run`
+with the same arguments at once.
+
+**5. What holds a search back.** Only two things: a mark that cannot be made out (absent, or with no
+clearly likely reading), and goods and classes both absent. Ask for the missing item, and start when the
+answer arrives. Nothing else holds a search:
+- A mark with one obvious mistyping is searched on the corrected reading, with the correction first in
+  the confirmation ("the form wrote NOVAPLUSE; searched as NOVAPULSE — say so if that is wrong").
+- A missing reference never holds a search.
+- An unknown applicant never holds one. Lead the second group with the question, set
+  `customerUnknown: true`, and start at once:
+
+> Who is the applicant? I've started the search — it doesn't depend on the answer — but until the
+> applicant is named I can't separate their own marks from third-party conflicts: an identical or
+> near-identical hit is reported as an ordinary conflict, carrying a note to disregard it if it's the
+> applicant's own prior filing. Reply as early as you can — I'll fold it in on a best-effort basis
+> while the search is still running.
+
+The answer goes in through `feed_context`. Never promise that an answer arriving any time before
+delivery will be folded in: a late answer is best effort.
 
 ## Starting a search — `start_run`
 
@@ -77,7 +124,14 @@ Extract from the request, faithfully (verbatim beats paraphrase):
   storefront that matters to them. These are ADDED to the account's own; you cannot remove theirs.
   Every one widens the grid, so pass only what was actually asked for.
 - **`ref`** (matter reference), **`deadline`** (ISO 8601 — drives deadline arithmetic), **`msgId`**
-  (your channel's native message id — the delivery packet threads the reply on it).
+  (your channel's native message id — the delivery packet threads the reply on it), and
+  **`conversationId`** (your channel's thread key, which the engine's duplicate check reads).
+- **`projectKey`** — the engagement under `profileKey`, from that customer's `projects` in
+  `list_profiles`, when the request names one or its list makes one unambiguous. Omit it otherwise.
+- **`customerUnknown: true`** — when the applicant is neither stated nor implied by who sent the request.
+- **`brief`** (the confirmation exactly as you sent it), **`rawRequest`** (the whole request, verbatim),
+  **`deliverableSpec`**, **`commercialFlexibility`** and **`priorUse`**, as plain text. Omit any that are
+  empty.
 - **`dupOverride: true`** — ONLY when the requester has explicitly confirmed a re-run of a matter
   the dedup gate parked. Never set it on your own initiative; a duplicate submission otherwise gets
   a polite duplicate-skipped notice, not a second spend.
@@ -87,7 +141,10 @@ The call returns the accepted job (or a validation refusal telling you exactly w
 
 ## While a run is in flight
 
-- **`get_run` / `list_runs`** — state, current step, verdict when reached.
+- **`get_run` / `list_runs`** — state, current step, verdict when reached. Answer a requester's "how is
+  it going?" from what these return. An engine you cannot reach and a search that has made no progress
+  are different facts: say "I could not reach the engine" for the first and "no progress since <time>"
+  for the second, and never report one as the other.
 - **`feed_context`** — fold in a mid-run answer (typically the applicant binding). One call; the
   engine acknowledges through the outbox.
 - **`decision_timeline`** — how the verdict evolved, when someone asks "why conditional?".