clearotron 0.3.2-beta.2 → 0.3.2-beta.3

package/.env.example

@@ -603,3 +603,13 @@ CLEAROTRON_DEMO_PROFILES=
 # it. Read by bin/start.mjs and shared/brand.mjs.
 # effect: deployment
 CLEAROTRON_ORGANISATION_NAME=
+
+# ── Who a person asks to change their sign-in ─────────────────────────────────────────────────────
+#
+# The administrator contact: a mail address (`it@example.com`, or `mailto:it@example.com`) or a web
+# address (`https://help.example.com/access`). Preferences tells a signed-in person to contact their
+# Clearotron administrator to change the address, the permissions or the companies on their sign-in;
+# set, those words are a link to this; unset, they are plain text. Any other value is treated as unset,
+# so nothing but a mail or web address ever becomes a link. Read by shared/brand.mjs.
+# effect: deployment
+CLEAROTRON_ADMINISTRATOR_CONTACT=

package/INSTALL.md

@@ -438,6 +438,8 @@ CLEAROTRON_CUSTOMERS_DIR=/etc/trademark/profiles # your private customer-config
 CLEAROTRON_BRAND_NAME=Your Firm           # stamped into report titles, the pool index and Excel metadata
 CLEAROTRON_BRAND_TAGLINE=                 # empty means ABSENT: no strapline is rendered at all
 CLEAROTRON_BRAND_PRODUCT=Trademark clearance   # what the deliverable is called
+# Optional: a mail or web address. Preferences links "Clearotron administrator" to it; unset, plain words.
+# CLEAROTRON_ADMINISTRATOR_CONTACT=it@your-firm.example
 
 # ── Register provider (choose ONE) ─────────────────────────────────────
 CLEAROTRON_DATABASE=clarivate       # REQUIRED — corsearch | clarivate | signa | euipo | uspto-local | free-tier

package/README.md

@@ -10,10 +10,11 @@
   <a href=".nvmrc"><img src="https://img.shields.io/badge/node-%E2%89%A5%2022.13-250902?style=flat-square" alt="Node 22.13+"></a>
 </p>
 
-Give it a mark, its classes and a territory. Clearotron searches the trademark registers and the open
-web for conflicts, reasons about the risk the way a clearance lawyer would, and publishes a written
-report with a machine-readable audit trail behind every finding. It runs headless on your own machine:
-no gateway, no platform, and nothing about your matters reaches us.
+Before your company commits to a name, find out what stands in its way. Give Clearotron the name, the
+classes you trade in and the territories you sell into: it searches the trademark registers and the
+open web for conflicts, reasons about the risk the way a clearance lawyer would, and publishes a
+written report with a machine-readable audit trail behind every finding. It runs headless on your own
+machine: no gateway, no platform, and nothing about the names you are clearing reaches us.
 
 [Quickstart](QUICKSTART.md) · [Install & operate](INSTALL.md) · [Docs](docs/README.md) · [Security](docs/SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Licence](#licence)
 
@@ -27,7 +28,7 @@ npx clearotron demo
 
 That fetches the published package — it will ask once before downloading — then replays finished
 clearances into a local portal and prints the portal's address and the passphrase to sign in with. Open
-the address in your browser. No account, no credentials, no network calls to us.
+the address in your browser. No sign-up, no credentials, no network calls to us.
 
 The demo runs for as long as that window stays open, and removes everything it made when you close it —
 nothing of it is left on the machine, and running it again later starts clean. If you want to keep the
@@ -82,8 +83,8 @@ Then start the product and open the portal address it prints:
 clearotron start
 ```
 
-That is the portal a brand owner uses. Ordering a clearance is the same screen — describe it in a
-sentence, or set the classes, marketplaces and search depth yourself:
+That is the portal everyone at your company uses. Ordering a clearance is the same screen — describe it
+in a sentence, or set the classes, marketplaces and search depth yourself:
 
 ![The new-clearance screen — classes, marketplaces and the four search depths](docs/assets/portal-new-clearance.png)
 
@@ -115,12 +116,16 @@ clearotron run --job my-job.json
   **HTTP** face whose read tools serve a signed-in identity while its write verbs — `start_run`
   among them, which spends — need an ops token. [Connect it](mcp-server/CONNECT.md).
 - **The engine is not coupled to a vendor.** [`driver/register-plan.mjs`](driver/register-plan.mjs) — which decides what gets searched — takes a capabilities object as a parameter and imports no provider at all. An unknown register id throws rather than falling back.
+- **A law firm runs one installation for every company it acts for.** Each company is set up once, with
+  its own classes, marketplaces and risk framework, and each person sees only the companies they are
+  given. [Adding a company](docs/ONBOARDING.md) · [A connector for those companies' people](docs/CLIENT-MCP.md).
 
 ## Security
 
-Reports carry client matter. Treat the pool, the archive and the delivery packets as you would a case file.
+Reports describe names your company has not announced yet. Treat the pool, the archive and the delivery
+packets as you would any unreleased plan — and, at a law firm, as you would a case file.
 
-**The authors of this software receive nothing** — no marks, no client context, no results, no usage
+**The authors of this software receive nothing** — no marks, no company context, no results, no usage
 reports, no crash reports. There is no telemetry in this tree and no endpoint we control: every
 destination is a register, a reasoning provider or a search provider you configured with your own
 credential.
@@ -139,7 +144,7 @@ credential.
 | Check it works before spending anything | [docs/E2E.md](docs/E2E.md) |
 | Understand the architecture | [docs/architecture/](docs/architecture/) · [decisions](docs/decisions/) |
 | Run it under your own name, or fork it | [docs/branding.md](docs/branding.md) · [TRADEMARKS.md](TRADEMARKS.md) |
-| Write a sentence a customer will read | [docs/writing-standard.md](docs/writing-standard.md) · [docs/writing-rules.md](docs/writing-rules.md) |
+| Write a sentence a user will read | [docs/writing-standard.md](docs/writing-standard.md) · [docs/writing-rules.md](docs/writing-rules.md) |
 
 ## Development
 

package/bin/onboard.mjs

@@ -2015,7 +2015,7 @@ export async function runCheck() {
   if (!prov) {
     blocking(`no register is selected — CLEAROTRON_DATABASE is not set and there is NO default, so every search refuses until one is`);
     info(`  set it to one of: ${PROVIDERS.map((p) => p.id).join(", ")} — any one of them is enough, and none needs another`);
-    info(`  re-run \`${invoke("install")}\`, or set it on the Global config page`);
+    info(`  re-run \`${invoke("install")}\`, or set it on the Installation settings page`);
   }
   else {
     const spec = PROVIDERS.find((p) => p.id === prov.v);
@@ -3565,7 +3565,7 @@ try {
   //
   // NOTHING DOWNSTREAM NEEDED CHANGING, and that is the owner's point rather than luck: CLEAROTRON_DATABASE
   // is single-valued with no default, a run already refuses by name when it is unset
-  // (driver.config.mjs), and the Global config page already renders "No register is selected."
+  // (driver.config.mjs), and the Installation settings page already says a register is needed.
   // One register per install, any one of them sufficient, none a precondition for another.
   let registerSelected = true;
   // What THIS step collected, so abandoning the selection can take it back. Measured: a register with
@@ -3591,7 +3591,7 @@ try {
     say("");
     info("No register is selected, and nothing register-related will be written.");
     info(`Every search refuses until one is set — \`${invoke("doctor")}\` says so on every run, and the`);
-    info("  Global config page says it too. Re-run setup, or set it there, when you have a credential.");
+    info("  Installation settings page says it too. Re-run setup, or set it there, when you have a credential.");
   }
   for (const k of registerSelected ? (spec.optionalCredentials ?? []) : []) {
     if (present(candidate[k])) { ok(`${k} already adopted from your environment`); continue; }
@@ -4142,7 +4142,7 @@ try {
     say(`    \`${invocationPrefix()}clearotron demo\` and \`${invocationPrefix()}clearotron start\` work now. A real`);
     say("    clearance needs one register — any one is enough, and none requires another:");
     say(`      ${PROVIDERS.map((p) => p.id).join(", ")}`);
-    say(`    Set it by re-running \`${invocationPrefix()}clearotron install\`, or on the Global config page.`);
+    say(`    Set it by re-running \`${invocationPrefix()}clearotron install\`, or on the Installation settings page.`);
     say(`    \`${invocationPrefix()}clearotron doctor\` says which state this install is in, at any time.\n`);
   }
 } catch (e) {

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "8393489759f73ec4177b2fce74005780b7b4a567",
-  "version": "0.3.2-beta.2"
+  "commit": "d4059c3a0c77911c1592fda411dc27948b4aaa95",
+  "version": "0.3.2-beta.3"
 }

package/docs/CLIENT-MCP.md

@@ -5,44 +5,44 @@ definitions.*
 
 > **Just want to connect your own app to your own runs?** You do not need any of this — spawn the stdio
 > server from your clone. [`mcp-server/CONNECT.md`](../mcp-server/CONNECT.md) is four lines of
-> copy-paste. This document is for publishing a connector your *customers* sign in to.
+> copy-paste. This document is for publishing a connector that each *company's* people sign in to.
 
-What a customer reaches once you have, what they cannot, and how to turn it on. For the staff/ops MCP
+What they reach once you have, what they cannot, and how to turn it on. For the staff/ops MCP
 faces see `docs/architecture/09-security-and-data.md`.
 
 ## The three faces, in one table
 
 One codebase (`mcp-server/server.mjs`), three processes. The separation is per-process **configuration**,
-never a runtime branch — "a client cannot reach staff read-all" is a fact about which binary is listening,
-not about a flag being right.
+never a runtime branch — "a company's person cannot reach staff read-all" is a fact about which binary is
+listening, not about a flag being right.
 
 | Face | Where it listens | Who | Reach |
 |---|---|---|---|
-| **Staff** | your staff hostname → `TRADEMARK_MCP_HTTP_PORT` (default 18790) | firm staff (staff CF Access AUD) | every read tool, all runs |
-| **Client** | your client hostname → `CLIENT_MCP_HTTP_PORT` (default 18811) | customers (client CF Access AUD) | see below |
+| **Staff** | your staff hostname → `TRADEMARK_MCP_HTTP_PORT` (default 18790) | your staff (staff CF Access AUD) | every read tool, all runs |
+| **Client** | your client hostname → `CLIENT_MCP_HTTP_PORT` (default 18811) | the people of each company (client CF Access AUD) | see below |
 | **Ops** | loopback only, on its own port, **no hostname** | the portal's trigger lane | reads + write verbs |
-| **API key** | a hostname with no Access app in front → its own `CLIENT_MCP_HTTP_PORT` | a client agent that cannot sign in | same as Client |
+| **API key** | a hostname with no Access app in front → its own `CLIENT_MCP_HTTP_PORT` | a company's agent that cannot sign in | same as Client |
 
 Every port above is the code default and each face is a separate process, so on one machine give
-each its own. The ops face is never on the internet. If you are looking for "the customer one", it
-is the Client face. The API-key door is that same client face reached with a credential instead of a
+each its own. The ops face is never on the internet. If you are looking for the face a company's people
+use, it is the Client face. The API-key door is that same client face reached with a credential instead of a
 browser login — see "The API-key door" below.
 
-## The two client principals
+## The two principals outside your staff
 
 **`user` — a run-bound report link.** A read-only token pinned to one run, no enumeration. The scope
 is served as it always was; what changed with the move to a single report document is how anyone
 comes by one. The token is minted into THE report's "Ask your AI" block against the STAFF connector
 (`CLEAROTRON_MCP_URL`, `render.mjs`), and `portal-report.mjs` strips that whole block for every non-staff
-reader at serve time — so **no client-facing surface hands one out any more**. A signed-in client
-reaches the connector as `account` instead, at an address the portal serves live from
+reader at serve time — so **no surface a non-staff reader sees hands one out any more**. A signed-in
+person reaches the connector as `account` instead, at an address the portal serves live from
 `/portal/api/mcp-access` (`CLEAROTRON_CLIENT_MCP_URL`, no baked credential). A run-bound link for a
 recipient who has no login is now a deliberate act:
 `node mcp-server/mint-token.mjs --scope user --run <runId>`.
 
-**`account` — a signed-in client.** A CF-verified client identity with **no token**, resolved to the
-accounts their email is granted (`CLEAROTRON_ACCESS_FILE` — the same guest list the portal's client door uses).
-Enrolment is therefore the portal's: no second credential to mint, rotate or revoke, and revoking portal
+**`account` — a signed-in person.** A CF-verified identity from outside your staff with **no token**,
+resolved to the companies their email is granted (`CLEAROTRON_ACCESS_FILE` — the same guest list the portal
+uses). Enrolment is therefore the portal's: no second credential to mint, rotate or revoke, and revoking portal
 access revokes this with it. **Off unless `CLIENT_MCP_ACCOUNT_ACCESS=1`.**
 
 **Who turns that on. The installer, since 2026-09-03** — ruling, settled
@@ -53,9 +53,9 @@ come from one authority, `enablePlan` in `shared/client-door.mjs`, which is also
 
 **This supersedes the 2026-08-31 ruling** *"On demand is fine"*, under which nothing at install and no
 rebuild's enable list could start this unit, because starting it WAS the consent that opened
-client-account access. The owner changed the posture knowingly: **the per-account key is the gate, not
-whether a process runs.** A door with no key issued refuses everything, which is the same protection by
-a mechanism that does not depend on a reader finding a verb.
+access for each company's people. The owner changed the posture knowingly: **the per-person key is the
+gate, not whether a process runs.** A door with no key issued refuses everything, which is the same
+protection by a mechanism that does not depend on a reader finding a verb.
 
 **`npx clearotron disconnect` therefore revokes a person, not a service** (Q3). It writes the caller's key
 ids to the denylist and strikes them from the record; it does not stop the unit and does not touch
@@ -63,58 +63,58 @@ ids to the denylist and strikes them from the record; it does not stop the unit
 `npx clearotron disconnect --everyone`, which states how many keys and how many people that is before
 acting — and does not stop the service either.
 
-An `account` principal reaches **eighteen** tools, for its own accounts only — everything carrying
+An `account` principal reaches **eighteen** tools, for its own companies only — everything carrying
 `accountSafe: true` in `TOOL_SCOPES` (`shared/scope.mjs`), and nothing else:
 
 | Layer | Tools |
 |---|---|
-| the report | `brief`, `read_artifact` (the report; `clientSummary` is retired from client reach and stays an ops-only internal source), `list_findings` (curated cards) |
+| the report | `brief`, `read_artifact` (the report; `clientSummary` is retired from this face and stays an ops-only internal source), `list_findings` (curated cards) |
 | the evidence behind it | `list_evidence`, `list_searches`, `get_search_coverage` |
 | the audit chain | `read_artifact` over `audit`, `narrative`, `registerFindings`, `commonLaw`, `caseLaw`, `matterContext` and `registerUnit:<axis>`; `list_findings` on the raw `kind` path; `get_finding`, `get_run`, `trace`, `decision_timeline` |
 | the run lifecycle | `list_runs`, `describe_options`, `plan_run`, `start_run`, `stop_run` |
 | what-if | `what_if_plan` (free), `what_if_run` (queues a sandbox job), `what_if_result` (collects it) |
 
-The evidence layer exists because a client lawyer defending a filing decision needs the records
+The evidence layer exists because a lawyer defending a filing decision needs the records
 under the report, not just its prose. It projects named structured fields and enums derived from
 them — `mcp-server/lib/evidence.mjs` states that there is no code path forwarding free prose, and
 that is the one declared exception to the scrub.
 
-**The audit chain is open by ruling, 2026-08-27** ("I don't see why we don't open it or just
-give it to clients. Ignore the call spend."). The same lawyer who needs the records also has to be
-able to show *how* the answer was reached, so the decision chain is client product now. Unlike the
+**The audit chain is open by ruling, 2026-08-27**, with the call spend set aside. The same lawyer who
+needs the records also has to be able to show *how* the answer was reached, so the decision chain is
+part of what this face serves now. Unlike the
 evidence layer this one does forward prose — a chain of reasoning is prose — so it is bounded a
 different way: `mcp-server/lib/audit-view.mjs` names the structural fields that travel and puts the
-surviving prose through the report's own client-safety passes, never a second copy of them.
+surviving prose through the report's own scrub passes, never a second copy of them.
 
 Three things stayed behind, and each has a reason rather than a habit:
 
 - **Cost.** `get_telemetry` and `get_provider_usage` exist to report model identity and billed
   counts. Every other decision-chain read is model-free by construction — `events.mjs`, `trace.mjs`
-  and `getStages` each say so on their own surface — so sealing exactly these two costs a client
+  and `getStages` each say so on their own surface — so sealing exactly these two costs the reader
   nothing of the chain.
 - **The engine's judgment of its own output.** `skepticFlags` and `seniorEyeReview` are the reviewers
   writing about our draft, the same class as the `withdrawn_reason` ruling. The verdict they
   produced travels; the critique does not.
 - **The unruled reads.** `get_coverage`, `search`, `search_runs`, `diff_artifact`, `run_changes`,
   `list_profiles`, delivery/outbox, `feed_context` and what-if. Nobody has decided what these should
-  show a client, and an undecided tool is denied — `get_search_coverage` is deliberately not
+  show a company's people, and an undecided tool is denied — `get_search_coverage` is deliberately not
   `get_coverage`, the latter being the engineering artifact-validity view.
 
 **What-if is a QUEUED JOB on this surface, and that is what keeps the door honest.** The remote faces
 never spawn the engine — `http-server.mjs` states it as a configuration fact and `lib/whatif.mjs`'s lazy
-import of `driver/pipeline.mjs` is what holds it — so a client's `what_if_run` does not execute. It
+import of `driver/pipeline.mjs` is what holds it — so a `what_if_run` on this face does not execute. It
 validates, enqueues into `<runDir>/_experiments/_queue/`, and returns an `experimentId`;
 `driver/whatif-worker.mjs`, drained by the runner in an OS service process, is what spawns the sandbox.
-The client collects the diff with `what_if_result`. The original run is never modified — the experiment
+The caller collects the diff with `what_if_result`. The original run is never modified — the experiment
 writes only under `_experiments/`.
 
 Four things about it are worth knowing before you offer it:
 
-- **The confirmation-token handshake stays, and a client must ALSO name the run.** A token is plain
-  base64url JSON that nothing signs, so a token-only call would slip past the account gate, which keys on
+- **The confirmation-token handshake stays, and the caller must ALSO name the run.** A token is plain
+  base64url JSON that nothing signs, so a token-only call would slip past the grant check, which keys on
   `runId`. Naming the run puts the grant check in the path; `whatIfEnqueue` then proves the token names
   the same run, so neither half can be satisfied alone.
-- **A client cannot choose the model.** The tier is cost and method both, and it is the one argument on
+- **The caller cannot choose the model.** The tier is cost and method both, and it is the one argument on
   the one tool that spends. Express the change with `instructions`.
 - **Nothing bounds the spend, by ruling.** `start_run` is stamped `clientPrincipal: true` at the
   chokepoint so `runCaps.dailyRuns` bites it; a what-if job carries no such stamp, because the owner
@@ -125,15 +125,15 @@ Four things about it are worth knowing before you offer it:
 - **It starts on the timer, not instantly.** The systemd `.path` unit watches the clearance queue dirs,
   not run dirs, so a queued what-if is picked up on the runner's 90s tick.
 
-**A forwardable report link did not move.** `USER_ARTIFACTS` gated `read_artifact` for both client
-kinds, so the account layer was given its own set (`ACCOUNT_ARTIFACTS`) rather than the shared one
+**A forwardable report link did not move.** `USER_ARTIFACTS` gated `read_artifact` for both principal
+kinds, so the `account` layer was given its own set (`ACCOUNT_ARTIFACTS`) rather than the shared one
 being widened: a run-bound `user` token rides inside a delivered PDF and can be forwarded to anyone,
-and the ruling was about clients the firm enrolled.
+and the ruling was about people the operator enrolled.
 
-## What a client sees of a report
+## What a company's people see of a report
 
-The client cut, which is **what THE report already shows them — no more, and no less**:
-`report.html` as served to a client through the portal's `readReport()`
+The cut, which is **what THE report already shows them — no more, and no less**:
+`report.html` as served to a non-staff reader through the portal's `readReport()`
 preparation (`mcp-server/lib/scrub.mjs` states the rule; `driver/portal-report.mjs` is the serve-time
 counterpart).
 
@@ -142,23 +142,23 @@ hash, and the `tier`/`label` card shorthand the report footer says is "removed o
 
 **Kept, deliberately:** the Methodology section and the register/common-law provider names. Both are in the
 delivered report already (`render.mjs` renders Methodology via `plainScopeNote`; provider names are named
-for provenance honesty). A scrubber stricter than the report would delete content the client was already
+for provenance honesty). A scrubber stricter than the report would delete content the reader was already
 sent and make the connector a different product from the PDF in their inbox. **If you want less exposed,
 change the report render or the serve-time preparation (`portal-report.mjs`) — it flows here for free.
 Never add an MCP-only rule.**
 
-## The daily allowance — read this before enabling a demo tenant
+## The daily allowance — read this before enabling a demo company
 
-A client starting a run over MCP spends real money. The control is `runCaps.dailyRuns` on the customer
+Someone starting a run over this face spends real money. The control is `runCaps.dailyRuns` on the company
 profile, enforced at the runner's admission gate (so it covers every door) plus a portal pre-check.
 
 It only bites jobs stamped `clientPrincipal: true`, and **that stamp is positive-only — absence means
-uncapped**. `authorize()` forces it for an `account` principal, so a client cannot omit it or pass `false`.
-Staff runs deliberately never consume a client's allowance.
+uncapped**. `authorize()` forces it for an `account` principal, so a caller cannot omit it or pass `false`.
+Staff runs deliberately never consume a company's allowance.
 
-**For a demo or pitch account, set `dailyRuns` low (1–2) and `maxQueued: 1`.** Without `dailyRuns` the
-account is uncapped by day and can exhaust the weekly engine capacity in a sitting. Prefer a synthetic
-account for demos so the data is disposable too.
+**For a demo or pitch company, set `dailyRuns` low (1–2) and `maxQueued: 1`.** Without `dailyRuns` the
+company is uncapped by day and can exhaust the weekly engine capacity in a sitting. Prefer a synthetic
+company for demos so the data is disposable too.
 
 ## The API-key door — for agents that cannot sign in
 
@@ -173,12 +173,12 @@ node mcp-server/mint-token.mjs --scope account --sub lawyer@acme.example [--acco
 ```
 
 **The key proves WHO; the grants file still decides WHAT.** `--sub` names an identity that must appear in
-`CLEAROTRON_ACCESS_FILE`, and the accounts are resolved from that file **on every request** — never baked into
+`CLEAROTRON_ACCESS_FILE`, and the companies are resolved from that file **on every request** — never baked into
 the token. `--accounts` is a CAP (an intersection on top of the grant) and can only narrow it. So there are
 two independent revocation levers: **delete the grants row** (instant, needs no re-minting) or **denylist
 the `jti`** (`TRADEMARK_MCP_TOKEN_DENYLIST`).
 
-It resolves to the **same `account` principal** as a signed-in client, so the tool set, `authorize()`, the
+It resolves to the **same `account` principal** as a signed-in person, so the tool set, `authorize()`, the
 scrub and `runCaps` above all apply unchanged — there is no second policy to keep in step.
 
 **It is a separate process, not a flag on the client door** (`CLIENT_MCP_TOKEN_ONLY=1`, its own
@@ -196,7 +196,7 @@ A key may be presented as `Authorization: Bearer <key>`, a bare `Authorization:
 say in which, and `?token=` is the fallback that needs no header at all. On the CF-fronted doors
 `Authorization` is deliberately **not** read as a trademark key: there it belongs to the proxy/agent.
 
-**Give a key a real account with real `runCaps`, never `generic`** — `generic` is cap-exempt, so a
+**Give a key a real company with real `runCaps`, never `generic`** — `generic` is cap-exempt, so a
 long-lived credential pointed at it can spend without limit.
 
 ### Standing it up
@@ -209,7 +209,7 @@ long-lived credential pointed at it can spend without limit.
    `CLIENT_MCP_ACCOUNT_ACCESS=1` + `CLEAROTRON_ACCESS_FILE`, and drop the CF AUD lines (unused here).
 3. Verify before exposing: `curl 127.0.0.1:<port>/healthz`; the boot log says `API-KEY door — no auth
    proxy in front`; an MCP `initialize` **without** a key is a 401.
-4. Mint a key, hand it over with the address. `tools/list` must be exactly the eleven account tools
+4. Mint a key, hand it over with the address. `tools/list` must be exactly the eleven `account` tools
    above — anything more means the door resolved a wider principal than `account`.
 
 ## Turning it on
@@ -227,19 +227,19 @@ template, and a placeholder that looks configured is worse than unset.**
    and `client ACCOUNT access ON`. Starting with the flag set and no grants file is a **FATAL**
    refusal, by design.
 4. At your edge: confirm the client hostname resolves to that port and that the **client** Access app
-   fronts it — not the staff one. Enrol the client emails on that app's policy.
+   fronts it — not the staff one. Enrol the addresses of each company's people on that app's policy.
 5. `CLEAROTRON_CLIENT_MCP_URL` must be set for the portal process too, or `/portal/api/mcp-access` answers
    `{url:null}` and the Use-your-AI screen correctly shows its empty state.
 
 The client connector address is served **live**: `/portal/api/mcp-access` reads `CLEAROTRON_CLIENT_MCP_URL`
-at request time, so a change reaches every client screen on the next load — no re-render involved. The
+at request time, so a change reaches every screen that shows it on the next load — no re-render involved. The
 render no longer reads this variable at all: the block baked into
 `report.html` is the STAFF connector (`CLEAROTRON_MCP_URL`), and it is stripped for non-staff readers at
 serve time.
 
-## What briefs the client's assistant
+## What briefs a company's assistant
 
-`skills/clearotron-client/SKILL.md`, served as the MCP `instructions` field on initialize — clients surface
+`skills/clearotron-client/SKILL.md`, served as the MCP `instructions` field on initialize — MCP clients surface
 it to their model on connect. It sets voice (plain language, no codes), the tool ladder, the verdict
 vocabulary, evidence drill-through, and the three "never"s.
 

package/docs/DELIVERY.md

@@ -152,9 +152,9 @@ cap. An integrator that only runs during the day leaves a failure unreported unt
 nothing in the product can compensate for that: the product composes the notice and records that it is
 owed, and sending is yours.
 
-**Two things that make that list incomplete, both silent.** A token scoped to named accounts sees only
-those accounts' runs, so a run for an account the token does not carry is invisible rather than absent —
-mint the integrator's token to cover every account it delivers for, and re-mint it when one is added.
+**Two things that make that list incomplete, both silent.** A token scoped to named companies sees only
+those companies' runs, so a run for a company the token does not carry is invisible rather than absent —
+mint the integrator's token to cover every company it delivers for, and re-mint it when one is added.
 And a `limit` you pass yourself is obeyed as given: for this query, do not pass one.
 
 The filesystem loop below remains equivalent for integrators that do have data-plane access.
@@ -194,29 +194,29 @@ double-sends (`.sent` guards it).
 
 ## One report per run
 
-A run publishes ONE report document per mark, on every lane. There is no internal variant and no client
-variant, and nothing writes `report.client.html` — internal working material (staff notes, the
+A run publishes ONE report document per mark, on every lane. There is no internal variant and no second
+one for outside readers, and nothing writes `report.client.html` — internal working material (staff notes, the
 model's register estimate) is not stripped from the report, it is not in the report: it lives in the
 audit workbook. Two renderings of one run is how the wrong link gets sent.
 
 Beside it the run publishes `report-data.json` (`schema: "report-data/1"`): the run as data — level
 identity, bands, per-mark points, evidence links, register counts. That is the input a bespoke,
-forwardable client email is drafted from. The engine composes exactly one email shape, a cover note
-pointing at the report; per-customer formatting is not a config knob.
+forwardable email is drafted from. The engine composes exactly one email shape, a cover note
+pointing at the report; per-company formatting is not a config knob.
 
 The second document was a real hazard while it existed: any surface that opened a report **by file
-path** bypassed the serve-time preparation, so a client-facing path pointed at the wrong file served
+path** bypassed the serve-time preparation, so a non-staff path pointed at the wrong file served
 the internal report. Two properties close that, and both are load-bearing for anyone building a
-client-facing surface on this engine:
+surface for non-staff readers on this engine:
 
-- **Publish writes one file.** No lane produces `report.client.html`, and the per-customer index
+- **Publish writes one file.** No lane produces `report.client.html`, and the per-company index
   (`customer/<key>/index.html`) links `report.html` (`publish/index.mjs`) with no split language.
 - **One preparation chokepoint.** What a non-staff reader receives is prepared by the portal's
   `readReport()` (`driver/portal-report.mjs`, `staff:false`), which removes the reader-visible
   deltas — `[internal]` review tails, the internal band/reviewer shorthand, the staff Ask-your-AI
   connector — in one place, rather than at render time into a second document.
 
-**A client-facing surface must read through `readReport()`, never open a report by path.** That is
+**A surface for non-staff readers must read through `readReport()`, never open a report by path.** That is
 the whole guarantee: the preparation is on the read, so a surface that skips it serves unprepared
 bytes. Pool directories from before the change may still hold a `report.client.html`; nothing reads
 those files, and `publish/pool-admin.mjs` deliberately leaves them alone rather than retrofitting
@@ -256,9 +256,10 @@ There is no preflight that fails a run before anything touches the pool, and no
   `deliveryFlagLines`): one plain sentence per failing check, with a count. The checks' own `detail`
   never leaves the internal lane — it quotes fetch causes, register URIs, model field names and
   instructions to whoever re-runs the job. **The cover note carries no machine-check block**, on
-  either lane: `emailBodyHtml` is sent verbatim to `forwarderEmail`, which on a client-started run is
-  the client's own address, and a failing internal check does not change what was searched, so that
-  reader cannot act on it. One enumeration surface, and it is the one the reviewer already opens.
+  either lane: `emailBodyHtml` is sent verbatim to `forwarderEmail`, which on a run started by someone outside
+  the operator's staff is that person's own address, and a failing internal check does not change what
+  was searched, so that reader cannot act on it. One enumeration surface, and it is the one the reviewer
+  already opens.
 
 ### The knockout lane runs a SUBSET of the predelivery lint
 
@@ -275,7 +276,7 @@ the store-rendered end-state: `publishKnockout` renders from validated `knockout
 `validateMergedFindings` plus the per-chunk validators are its own lint — schema, ladder vocabulary,
 plan-parity, degraded-parity, tone, quantitative claims, URL receipts. Most clearance checks then
 read surfaces this lane does not produce: no register record store (it counts hits, it does not
-retrieve records), no actions register, no verdict sidecar, no client summary, no card assembly, no
+retrieve records), no actions register, no verdict sidecar, no `clientSummary`, no card assembly, no
 reviewer correction cycle, no intake-ask register.
 
 So the checks that run are exactly those whose whole input is model-authored text —

package/docs/E2E.md

@@ -89,15 +89,15 @@ frozen demo profile, and the file to open to prove which profile resolved).
 
 ### Tier 1b — the UI PORTAL (browse the dev instance; develop UI features against it)
 
-The pool already contains the whole UI (archive index, per-run report + client report + audit
-workbook, per-customer pages); production serves it with a real web server behind the auth proxy.
+The pool already contains the whole UI (archive index, per-run report + audit workbook, per-company
+pages); production serves it with a real web server behind the auth proxy.
 The dev stand-in is `driver/dev-portal.mjs` — zero-dep, **loopback-only** (refuses anything else):
 
 ```bash
 CLEAROTRON_REPORTS_DIR=$HOME/trademark-dev/pool node driver/dev-portal.mjs   # http://127.0.0.1:18899/
 ```
 
-- `/` → the archive index · `/<run>/report.html` → the report · `/customer/<key>/` → customer pages
+- `/` → the archive index · `/<run>/report.html` → the report · `/customer/<key>/` → company pages
 - `/profiles.html` + `/profiles/*` → the profile editor UI + a reverse-proxy to the profile-service
   (run that in ITS dev mode: `PROFILE_AUTH_DISABLED=1 PROFILE_DEV=1 PROFILE_PORT=<dev port>`)
 - the MCP HTTP face runs separately in its own dev mode (`TRADEMARK_MCP_DEV=1
@@ -115,7 +115,7 @@ so a dev instance beside a live one must be given its own (`PORTAL_PORT`, `PROFI
 silently — each is a proxy to a port, and the port is all it knows. `/recipes/*` is the worse half:
 its save endpoint writes and git-commits into whichever recipe store it reached.
 
-A pass here looks like: index, run report, the demo customer page and the profile-editor UI all
+A pass here looks like: index, run report, the demo company's page and the profile-editor UI all
 render against the Tier-1 pool; the `/profiles/*` proxy round-trips; traversal and non-loopback binds
 are refused (unit-tested).
 
@@ -147,8 +147,8 @@ correct.
 ## Tier 3 — the paid cutover run (once, ~$40)
 
 Same loop as Tier 2 with the real engine (`CLEAROTRON_CLAUDE_PATH=claude`) + real provider credentials +
-a real matter. Validates model/vendor OUTPUT QUALITY, not machinery (Tiers 0–2 already proved that).
-Run it once, at cutover — it bills a real matter against real vendor credentials, so it is not a
+a real request. Validates model/vendor OUTPUT QUALITY, not machinery (Tiers 0–2 already proved that).
+Run it once, at cutover — it bills a real clearance against real vendor credentials, so it is not a
 loop you repeat to debug something Tier 1 could have shown you.
 
 ## Engine selection is process-wide — what that rules out
@@ -159,7 +159,7 @@ stage of every job in that activation**. There is no per-stage override and no p
 
 Two round shapes this rules out, worth knowing before a plan assumes them:
 
-- **A same-instance parallel A/B is not available.** Comparing codex against anthropic on one matter
+- **A same-instance parallel A/B is not available.** Comparing codex against anthropic on one request
   means flipping `CLEAROTRON_AI` and running the arms **sequentially**, or standing up a second instance
   with its own env, pool and ports. Two engines cannot run concurrently under one driver.
 - **Reviewer family diversity is not available** by routing one stage elsewhere. Sending the refutation
@@ -195,7 +195,7 @@ model-attributable — on 2026-08-15. Each failure was cheap; the sequence was n
 
 **Ask whether the artifacts already separate the variables, before spending a run.** That question was
 finally answered with no new run at all: within the runs already in hand, two axes were clean 9/9 while
-a third faulted 9/9 — same model, same matter, same date, same provider. A within-run comparison
+a third faulted 9/9 — same model, same mark, same date, same provider. A within-run comparison
 attributes by construction. Three runs were spent discovering that.
 
 **Read the instrument's own vitals before you read its result.** One of the three failures was a spawn

package/docs/GLOSSARY.md

@@ -2,8 +2,8 @@
 
 Words this codebase uses in a particular way. They are here because they are already in the tree —
 in file names, comments and test titles — and a contributor meeting one should not have to reverse
-it out of the code. Product vocabulary a client would meet is in [`../README.md`](../README.md); the
-tenant, account and project model is in [`../INSTALL.md`](../INSTALL.md) under "The four things, and
+it out of the code. Product vocabulary a user meets is in [`../README.md`](../README.md); the
+organisation, company and project model is in [`../INSTALL.md`](../INSTALL.md) under "The four things, and
 what contains what".
 
 Nothing here is a rule. Each line says what the word points at, and names the file that owns it.

package/docs/INTAKE.md

@@ -43,11 +43,11 @@ the default agent's workspace queue.
   - neither `classes` (or `marks[].classes`) **nor** a goods description (`goods`/`use`) —
     either one suffices, and the request is not the only place classes may come from. When it
     names none, the door resolves the same ladder the run does (request → saved search →
-    project overlay → customer profile, `effective-scope.mjs`) and admits the job if any layer
+    project overlay → company profile, `effective-scope.mjs`) and admits the job if any layer
     supplies them, recording which one in a warning. A request under a project that carries the
     classes is therefore admitted, not clarified. The clarify stands only when no layer has any,
     and it then names what was consulted
-  - a `profileKey` that names no known customer (a typo must clarify, never silently
+  - a `profileKey` that names no known company (a typo must clarify, never silently
     mis-route to the generic profile on a paid run)
   - an unknown `product`/`recipeKey`, both selectors set at once, a `deliveryRoute`
     outside `email | portal`, `caseLaw` or `nativeLanguage: false` (neither is a request setting —
@@ -70,7 +70,7 @@ the default agent's workspace queue.
 
 Other consumed fields (see `EXAMPLE_JOB` in `enqueue-schema.mjs` for the full annotated shape):
 `forwarderEmail`, `forwarderDomain`, `provider`, `marks[] = [{ref,name,classes}]`, `customer`
-(applicant → self-exclusion set), `profileKey` (customer account → profile/framework/template),
+(applicant → self-exclusion set), `profileKey` (the company → profile/framework/template),
 `upfrontInstructions`, `brief`, `rawRequest`, `deliverableSpec`, `commercialFlexibility`,
 `priorUse`, `deadline` (ISO-8601, drives the deadline envelope), `enqueuedAt`, and
 `conversationId` — best-effort email-thread id consumed by the **matter dedup** below.
@@ -79,11 +79,11 @@ machinery runs:
 
 - `jurisdictions` — the instructed territories, e.g. `["US","EU","JP"]`. Present ⇒ **authoritative**:
   the matter frame is told not to widen past them, the register plan derives its regions from them and
-  the native-language lanes deepen only inside them. Omit ⇒ the project/customer `defaultJurisdictions`. Names and
-  codes both read; deduped case-insensitively; max 20.
+  the native-language lanes deepen only inside them. Omit ⇒ the project's or the company's
+  `defaultJurisdictions`. Names and codes both read; deduped case-insensitively; max 20.
 - `platforms` — extra marketplaces to sweep, as bare store domains. **Additive only**: unioned onto
-  the account's own before the profile freeze, so the common-law grid floor and batch size re-derive
-  from the surface actually swept. A request can widen a client's mandated marketplaces and has no way
+  the company's own before the profile freeze, so the common-law grid floor and batch size re-derive
+  from the surface actually swept. A request can widen a company's mandated marketplaces and has no way
   to narrow them. Max 10; `web` is implicit and must not be listed.
 
 `platforms` belongs to the **clearance** pipeline alone. A knockout has no marketplace grid to add to
@@ -98,13 +98,13 @@ the instructed territories when the request names any, and "Global — all juris
 names none (`driver/stages-knockout.mjs`).
 
 Selection fields (`driver/products.mjs` declares the four): `product` (one of the four in the offering), `recipeKey` (a
-saved customer search — mutually exclusive with `product`), `nativeLanguage` (the one toggle, and only
+company's search template — mutually exclusive with `product`), `nativeLanguage` (the one toggle, and only
 on a Multi-country focus search — `true` adds it, and `false` is refused because it never switched
 anything off), `geography` (`{mode: worldwide|named|account-default}` — stated,
 because "everywhere" and "I said nothing" resolve differently), `deliveryRoute` (`email` default |
 `portal`), `parentRunId` (escalation lineage). `caseLaw` is NOT a field: it is what a Full country
 search IS, and sending it is refused rather than dropped. The runner's admission gate resolves
-job → project → customer → **the resolved scope** and PARKS AS CLARIFY any selection this
+job → project → company → **the resolved scope** and PARKS AS CLARIFY any selection this
 build/deployment cannot run — never a silent substitution, never a drop.
 
 ### Prose sidecars (optional)
@@ -141,10 +141,10 @@ above each queue:
 
 - **signature** dimension: normalized `forwarder|mark|classes|customer|ref`
 - **thread** dimension: same `conversationId` **and** same mark (distinct marks forwarded in
-  one email are separate matters and all run)
+  one email are separate requests and all run)
 
 A duplicate parks as `.duplicate` (recoverable), never runs. `"dupOverride": true` is the
-explicit requester-confirmed force-run (it still records the matter, so later true duplicates
+explicit requester-confirmed force-run (it is still recorded, so later true duplicates
 are caught). A **failed** run drops its ledger entry so a genuine re-send is never blocked.
 
 ## Relevant environment