clearotron 0.3.2-beta.2 → 0.3.2-beta.4

package/docs/ONBOARDING.md

@@ -1,18 +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 -->
 
-# Onboarding a brand owner
+# Onboarding a company
 
 One page, one command.
 
-A brand owner is a client whose matters this deployment searches. Onboarding one means creating its
-bundle in the customer store and choosing the risk framework its matters are rated under. Before this
-page existed the command shipped and no document mentioned it, so an operator following the docs
-hand-edited JSON in a directory holding real client material.
+A company is a business whose names this installation clears — your own, or one you clear names for.
+Onboarding one means creating its bundle in the company store and choosing the risk framework its
+clearances are rated under. The command still says `brandowner`, the word it used before the product
+settled on company. Before this page existed the command shipped and no document mentioned it, so an
+operator following the docs hand-edited JSON in a directory holding real companies' material.
 
 ## Before you start
 
-You need the customer store. `CLEAROTRON_CUSTOMERS_DIR` names it, and the command refuses by name if it
+You need the company store. `CLEAROTRON_CUSTOMERS_DIR` names it, and the command refuses by name if it
 is unset or unreadable rather than writing somewhere else. It is the private config repository described
 in `docs/architecture/05-config-governance.md` — not part of this repository, and not created by the
 installer.
@@ -29,11 +30,11 @@ malformed one is refused before anything is written.
 | option | |
 |---|---|
 | `--name` | the legal name. Required. |
-| `--domains` | comma-separated email domains that resolve to this owner |
+| `--domains` | comma-separated email domains that resolve to this company |
 | `--platforms` | marketplaces their searches cover. Omitted, the default's platforms apply and are named in the output. |
 | `--framework` | their risk framework, as `skills/prelim-search/<file>.md`. Omitted, the default applies and is named in the output. |
 | `--industry` | free text, shown on their profile |
-| `--context` | a file whose contents become this owner's context pack |
+| `--context` | a file whose contents become this company's context pack |
 | `--dry-run` | say exactly what would be written, and write nothing |
 
 **Run it with `--dry-run` first.** It prints the same decisions and the same refusals against the same
@@ -48,9 +49,9 @@ prints which one it used.
 **Absent and broken are different events, deliberately.**
 
 - **You gave no `--framework`.** The default applies, and the output names it. Onboarding proceeds —
-  a client who has not sent us their framework yet is not a reason to refuse them.
+  a company without a framework of its own yet is not a reason to refuse it.
 - **You gave one and it cannot be read.** The command refuses and writes nothing. Falling back here
-  would rate a client's matters under a framework nobody chose, while the operator believed they had
+  would rate a company's clearances under a framework nobody chose, while the operator believed they had
   set theirs — silently, which is the part that makes it worth an exit code.
 
 Read the line that names the framework. It is the whole receipt for a decision you cannot see in the
@@ -71,12 +72,12 @@ plainly shows. Reconcile it before onboarding anything else.
 
 ## After it succeeds
 
-The owner's profile is readable by the portal and by the engine, and their Brand profile page shows the
-framework's title and bands. Order a first clearance for them the way you order any other — through the
-portal, or through the MCP door described in `docs/CLIENT-MCP.md`.
+The company's profile is readable by the portal and by the engine, and its profile page in the portal
+shows the framework's title and bands. Order a first clearance for it the way you order any other —
+through the portal, or through the MCP door described in `docs/CLIENT-MCP.md`.
 
 ## What this page does not cover
 
-Editing an existing owner, and the validation the portal's own profile form applies. Both are the
-profile service's, not this command's — a client body may not introduce a framework selection, and that
-refusal is deliberate and is documented with the service rather than here.
+Editing an existing company, and the validation the portal's own profile form applies. Both are the
+profile service's, not this command's — a save from the portal may not introduce a framework selection,
+and that refusal is deliberate and is documented with the service rather than here.

package/docs/PORTAL.md

@@ -1,6 +1,6 @@
 # The portal
 
-*One address and one login, for staff and clients alike.*
+*One address and one login, whoever is signing in.*
 
 **Two ways to prove who you are, and one place that decides what you see.** Hosted,
 `PORTAL_AUTH_MODE=auth-proxy` means any login system in front that authenticates in the browser and
@@ -53,9 +53,9 @@ burned it.
   sign-in form, not a screen in `portal-ui`. The names are reserved on every deployment, so behind CF
   Access they 404 rather than rendering the app shell. A signed-out browser is redirected here; a
   signed-out API caller gets the same 401 the edge produces for a missing JWT.
-- `GET /portal/api/searches?account=` — registry levels + the account's saved recipes.
+- `GET /portal/api/searches?account=` — registry levels + the company's saved recipes.
 - `POST /portal/api/run/plan` — the **confirmation gate**: validation, the registry-derived
-  stage label (never a client's recipe label), mark count, turnaround hint, the standing caveat, and
+  stage label (never a company's recipe label), mark count, turnaround hint, the standing caveat, and
   a 10-minute HMAC `confirmationToken` bound to the fields of the server-stamped job that fix scope,
   cost and identity (`jobHashOf`: marks, markName, classes, goods, product/recipeKey), the confirming
   identity, and a ONE-SHOT jti. Jurisdictions are deliberately OUTSIDE the hash, so the plan step can
@@ -63,7 +63,7 @@ burned it.
   spends here.
 - `POST /portal/api/run` — re-runs the plan gates, verifies the token (a mutated request, another
   sign-in's token, or a replay all 409) then triggers via **real MCP JSON-RPC over the ops face's
-  `/mcp`** (`driver/portal-mcp-client.mjs`: initialize → tools/call with the accounts-scoped
+  `/mcp`** (`driver/portal-mcp-client.mjs`: initialize → tools/call with the company-scoped
   `PORTAL_OPS_TOKEN`; wire shape test-pinned against the face's own handler) — the portal's blast
   radius is that token's grant, enqueue-only, and scoped tokens must name `profileKey` explicitly.
   Job identity (profileKey, forwarder, forwarderEmail) is SERVER-stamped from the verified principal;
@@ -73,20 +73,21 @@ burned it.
   and copied into `meta.json` by the clearance publisher.
 - `GET /portal/api/runs?account=` — delivered pool rows (released reports linked; held runs listed
   unlinked) + live workspace rows.
-- `GET /portal/report/<runId>/` — the CLIENT export, ownership-checked; foreign/held/missing = 404.
-- `GET /portal/admin/*` — staff-only (clients get 404).
+- `GET /portal/report/<runId>/` — the report as the people it belongs to see it, ownership-checked;
+  foreign/held/missing = 404.
+- `GET /portal/admin/*` — staff-only (everyone else gets 404).
 
-Every plan/trigger is audited to `PORTAL_AUDIT` (JSONL, verified email + account + selector).
+Every plan/trigger is audited to `PORTAL_AUDIT` (JSONL, verified email + company + selector).
 
-## Per-account admission caps (`runCaps`)
+## Per-company admission caps (`runCaps`)
 
-Customer-profile key (visible, git-tracked — never a hidden env var). The closed key set is
+Company-profile key (visible, git-tracked — never a hidden env var). The closed key set is
 `{maxQueued?, dailyRuns?, monthlyRuns?}`, at least one required when the block is present
 (`driver/profiles.mjs`) — for example
 `"runCaps": { "maxQueued": 3, "monthlyRuns": 40 }` — enforced at the runner's `claimAndPrep`
 chokepoint for EVERY door (email, CLI, MCP, portal). Over-cap **clarifies** (requester notified,
 re-sendable), never drops. Monthly counting rides the matter ledger (now stamped with `profileKey` +
-`enqueuedBy`); queued counting scans the queue manifests' tags. Customer-only (a project cannot
+`enqueuedBy`); queued counting scans the queue manifests' tags. Company-only (a project cannot
 widen caps). `runCaps` is one of the `CODE_OWNED_FIELDS` (`driver/profile-service.mjs`): the profile
 editor has no form field for it and preserves whatever is on file across a save, so it is edited in
 the profile JSON and never lost by a form that does not mention it.
@@ -136,7 +137,7 @@ clear. Put a TLS-terminating proxy in front if it has to be reachable.
 
 Grants fixture: `{"tenants":{"demo":{"accounts":["foxglade"],"users":{"cli@celta.example":["foxglade"]}}}}`.
 
-The trigger lane needs the MCP HTTP face and an accounts-scoped ops token; without both, the run step
+The trigger lane needs the MCP HTTP face and a company-scoped ops token; without both, the run step
 reports the trigger lane unwired and the plan step still works. **The face no longer has to be run in
 its dev bypass to provide that**:`TRADEMARK_MCP_AUTH_MODE=token` runs it with a mandatory scoped
 access key and no auth proxy — loopback only, and refused outright alongside
@@ -174,7 +175,7 @@ the model.
 **The procedure:**
 
 1. Put the proxy in front of the portal's port and make it require sign-in. The portal must not be
-   reachable except through it — an origin a client can reach directly is an origin with no door.
+   reachable except through it — an origin anyone can reach directly is an origin with no door.
 2. Set `PORTAL_AUTH_MODE=auth-proxy` and the four values above in `.env`.
 3. `npx clearotron doctor` — the **Portal door** section reports which door is configured and which of
    the four values are present, by name. It never prints their values.
@@ -200,13 +201,14 @@ no proxy in front is the one shape to avoid: `doctor` reports the fronted door w
 absent, and the portal refuses to start without an issuer. If you want the passphrase door, say
 `PORTAL_AUTH_MODE=local`.
 
-## How a run gets its account
+## How a run gets its company
 
 `runAccountKey` (`mcp-server/lib/runs.mjs`) reads the run's own frozen profile sidecar
 (`_driver/profile.json`) and takes `profileKey`, falling back to `key`. That key is what grants
-scoping filters on, so a run whose sidecar carries neither is untagged and reaches no client surface.
+scoping filters on, so a run whose sidecar carries neither is untagged, and only a person with access to
+everything sees it.
 
-The write side is gated the same way. An accounts-scoped token can only dequeue jobs inside its
-grant — `stop_run` checks the account on the queue form as well as on a live run — and every
+The write side is gated the same way. A company-scoped token can only dequeue jobs inside its
+grant — `stop_run` checks the company on the queue form as well as on a live run — and every
 `start_run` stamps the verified token `sub` into the job as `enqueuedBy`, ignoring any value the
 body supplied.

package/docs/README.md

@@ -25,7 +25,7 @@ the vendor flags approximate is UNKNOWN, never a number.
 
 | Doc | What it answers |
 |---|---|
-| [`configuration.md`](configuration.md) | Registers, risk frameworks, client profiles — the practice-level settings |
+| [`configuration.md`](configuration.md) | Registers, risk frameworks, company profiles — the settings that make an installation its own |
 | [`architecture/04-configuration-reference.md`](architecture/04-configuration-reference.md) | Every environment variable, with ownership tiers |
 | [`architecture/05-customer-profiles.md`](architecture/05-customer-profiles.md) | Profile internals and the onboarding runbook |
 
@@ -36,7 +36,7 @@ the vendor flags approximate is UNKNOWN, never a number.
 | [`INTAKE.md`](INTAKE.md) | How a job reaches the runner — the headless queue contract |
 | [`DELIVERY.md`](DELIVERY.md) | What the engine emits when a run finishes, and who sends it |
 | [`PORTAL.md`](PORTAL.md) | The portal: what it serves, and who sees what |
-| [`CLIENT-MCP.md`](CLIENT-MCP.md) | Publishing a connector your customers sign in to, and how their access is scoped. To connect *your own* app to *your own* runs, use [`../mcp-server/CONNECT.md`](../mcp-server/CONNECT.md) instead |
+| [`CLIENT-MCP.md`](CLIENT-MCP.md) | Publishing a connector that each company's people sign in to, and how their access is scoped. To connect *your own* app to *your own* runs, use [`../mcp-server/CONNECT.md`](../mcp-server/CONNECT.md) instead |
 | [`E2E.md`](E2E.md) | Proving a deployment works end to end |
 | [`GLOSSARY.md`](GLOSSARY.md) | The words this codebase uses in a particular way — one line each, for a contributor meeting them for the first time |
 | [`SECURITY.md`](SECURITY.md) | The security envelope — what protects what, and where it is enforced in code. To report a vulnerability, use [`../SECURITY.md`](../SECURITY.md) |
@@ -47,13 +47,13 @@ tokens is [`architecture/06-operations-runbook.md`](architecture/06-operations-r
 what you set at install time, including the four variables that keep two instances on one machine
 apart, is [`../INSTALL.md`](../INSTALL.md) §8.
 [`../examples/grants.example.json`](../examples/grants.example.json) is a runnable guest list over the
-demo clients.
+demo companies.
 
 ## Architecture
 
 [`architecture/`](architecture/) is the reference pack: product overview, run lifecycle, the
 configuration reference, the
-[config-governance inventory](architecture/05-config-governance.md), customer profiles, quality and
+[config-governance inventory](architecture/05-config-governance.md), company profiles, quality and
 audit, security and data, and the
 [development guide](architecture/08-development-guide.md) — which is where to look before adding a
 stage, an engine adapter, or a register provider.
@@ -64,8 +64,8 @@ mechanically; it is a convention held by review.
 
 ## What this repo contains, and what it does not
 
-**No client data.** No client names, no marks under clearance, no matter numbers, no run identifiers.
-A guard sweeps every tracked file for client identity,
+**No data from a real clearance.** No names of the companies it cleared for, no marks under clearance, no
+matter numbers, no run identifiers. A guard sweeps every tracked file for a real company's identity,
 and a second sweeps for operator identity and for any
 citation of a path withheld at the public cut — that second one reads a list of withheld paths
 carrying a reason per entry, and fails a citation of one that is not declared. Both are tests in the contributor
@@ -77,10 +77,10 @@ The other half is structural: it fails on any undeclared identity inside a matte
 which is the half that catches something new. Without the private table the guard runs on synthetic
 sentinels: the machinery is exercised and there is nothing real to find.
 
-**Demo clients are synthetic.** The published package carries a Generic default (`generic`) and one
-demo brand owner. The repository holds three further invented accounts — gaming, functional drinks and
-animal health — which exercise the per-client machinery and the test suite and are never published.
-Real client bundles load at runtime from a private store (`CLEAROTRON_CUSTOMERS_DIR`) and are never
+**Demo companies are synthetic.** The published package carries a Generic default (`generic`) and one
+demo company. The repository holds three further invented companies — gaming, functional drinks and
+animal health — which exercise the per-company machinery and the test suite and are never published.
+Real company bundles load at runtime from a private store (`CLEAROTRON_CUSTOMERS_DIR`) and are never
 committed here.
 
 **Real third-party names are deliberate.** Registers, marketplaces, regulators, research providers and

package/docs/SECURITY.md

@@ -10,9 +10,9 @@ here corresponds to shipped behavior; when hardening changes, change this file i
 | Surface | Trust | Guard |
 |---|---|---|
 | stdio MCP (`mcp-server/server.mjs`) | local/full ("ops") | OS user boundary — run it AS the operator account; it is the only surface on which `what_if_run` EXECUTES (`visibleTools` keeps what-if out of the HTTP listing for ops, but the CallTool chokepoint gates on `authorize()` alone, which admits it for any ops token not `--verbs`-scoped) |
-| Client MCP (`mcp-server/http-server-client.mjs`) | signed-in client / account key | a client account's `what_if_run` ENQUEUES rather than executes (ruling 2026-08-27) — it never imports the engine, and `driver/whatif-worker.mjs` spawns the sandbox from an OS service process. A confirmation token is unsigned, so the call must ALSO name its `runId`: the account gate keys on it, and `whatIfEnqueue` refuses a token naming a different run. The `model` argument is refused to a client. |
+| Client MCP (`mcp-server/http-server-client.mjs`) | a company's signed-in person / their access key | `what_if_run` from an `account` principal ENQUEUES rather than executes (ruling 2026-08-27) — it never imports the engine, and `driver/whatif-worker.mjs` spawns the sandbox from an OS service process. A confirmation token is unsigned, so the call must ALSO name its `runId`: the grant check keys on it, and `whatIfEnqueue` refuses a token naming a different run. The `model` argument is refused on this face. |
 | HTTP MCP (`mcp-server/http-server.mjs`) | authenticated remote | auth-BEFORE-data; fail-closed construction; inner scoped tokens |
-| Report "Ask your AI" links | external report recipients | run-bound `user` tokens minted at publish; client layer only |
+| Report "Ask your AI" links | external report recipients | run-bound `user` tokens minted at publish; the plain-language report tools (`clientSafe`) only |
 | Dev portal (`driver/dev-portal.mjs`) | dev only | loopback-only (throws on any other host); never production serving |
 
 ## Authentication (the outer gate — both faces)
@@ -77,17 +77,17 @@ with access to everything.
 
 ## Authorization (the inner gate — both faces; `shared/scope.mjs`, enforced at ONE chokepoint)
 
-- Four principal kinds: **ops** (write verbs; automation/operator), **user** (read-only, pinned to
-  exactly ONE run — report recipients), **account** (a signed-in client across the accounts their
-  identity is granted: the client layer, the evidence layer — `list_evidence` / `list_searches` /
+- Four principal kinds: **`ops`** (write verbs; automation/operator), **`user`** (read-only, pinned to
+  exactly ONE run — report recipients), **`account`** (a signed-in person across the companies their
+  identity is granted: the plain-language report tools, the evidence layer — `list_evidence` / `list_searches` /
   `get_search_coverage` — the AUDIT CHAIN (ruling 2026-08-27: `read_artifact` over the chain
   artifacts named in `ACCOUNT_ARTIFACTS`, `list_findings` on the raw `kind` path, `get_finding`,
   `get_run`, `trace`, `decision_timeline`), WHAT-IF as a queued sandbox job (`what_if_plan`,
   `what_if_run`, `what_if_result`), and the run lifecycle on their own runs, and nothing else. All of it accountSafe and deliberately NOT clientSafe, because a report link is forwardable
-  and an account is an enrolled identity), **internal** (authenticated staff, read-all, no writes).
-- **What an account still cannot read, and why each one**: `get_telemetry` / `get_provider_usage`
-  (model identity and billed counts — the firm's cost structure, and the only two tools that carry
-  either, so sealing them costs the client nothing of the chain); the `skepticFlags` /
+  and an `account` principal is an enrolled identity), **`internal`** (authenticated staff, read-all, no writes).
+- **What an `account` principal still cannot read, and why each one**: `get_telemetry` / `get_provider_usage`
+  (model identity and billed counts — the operator's cost structure, and the only two tools that carry
+  either, so sealing them costs the reader nothing of the chain); the `skepticFlags` /
   `seniorEyeReview` artifacts (the reviewers' judgment of the engine's OWN output — the verdict they
   produced travels, the critique does not); `status.json` / `run.jsonl` (JSON that the markdown
   scrub would pass through untouched, carrying the run codename, the agent id, absolute paths and
@@ -102,15 +102,15 @@ with access to everything.
   omitted runId pinned), reach any write/spend tool, or read internal artifacts — `read_artifact`
   is name-gated to the report alone (`USER_ARTIFACTS`), and `list_findings` to the curated
   report-card groups, so the raw audit trail stays sealed. **The 2026-08-27 audit-chain ruling did
-  not move this line.** `USER_ARTIFACTS` gated `read_artifact` for both client kinds, so the account
+  not move this line.** `USER_ARTIFACTS` gated `read_artifact` for both non-staff kinds, so the `account`
   layer was given its own `ACCOUNT_ARTIFACTS` rather than the shared set being widened: a user token
-  rides inside a delivered PDF and can be forwarded to anyone, and the ruling was about clients the
-  firm enrolled. Both sets are gated at the read_artifact tool AND at the Resources surface
+  rides inside a delivered PDF and can be forwarded to anyone, and the ruling was about people the
+  operator enrolled. Both sets are gated at the read_artifact tool AND at the Resources surface
   (`resources/list` / `resources/read`), kind for kind — two doors to the same bytes, one rule.
 - **Ops tokens are least-privilege**: an optional `verbs[]` allowlist restricts write tools per
   principal (an intake connector physically cannot `stop_run`). `what_if_*` is filtered out of the
   HTTP tool LISTING for every OPS scope (`visibleTools`, keyed on `local` — the `local` test governs
-  the ops branch only, and a client account returns above it). That is hygiene, not a wall:
+  the ops branch only, and an `account` principal returns above it). That is hygiene, not a wall:
   `authorize()` never sees `local` and treats what-if as an ordinary ops write verb, so an ops token
   minted without `--verbs` can still call it over HTTP — which is why every HTTP ops token should be
   minted verb-scoped.
@@ -124,7 +124,7 @@ what the mechanism guarantees.*
   principal in every audit line; the `jti` printed at mint time is the revocation handle). Two
   automatic minters sit beside it on the same `mintToken`: the clearance publisher mints the report
   link's run-bound `user` token at publish, and `npx clearotron start` mints the portal's verb-scoped,
-  account-capped ops token in memory at every start. Neither prints, and neither is written down.
+  company-capped ops token in memory at every start. Neither prints, and neither is written down.
 - **Revocation**: denylist file checked on every verification; missing file = nothing revoked (the
   denylist can never take all auth down). **Rotation**: two-secret window, flag-day-free.
 - **Rate limits**: per-identity bucket on every request plus a separate lower per-principal bucket
@@ -138,9 +138,9 @@ principal) and before dispatch; it is best-effort and never blocks a request.
 
 ## Data plane
 
-- **No client data in this repository — structural, not procedural.** Real customer bundles live in
-  an external store (`CLEAROTRON_CUSTOMERS_DIR`/`CLEAROTRON_INSTRUCTIONS_DIR`); the repo ships synthetic demo
-  customers only. Run data lives in operator-owned directories outside git (`CLEAROTRON_REPORTS_DIR`,
+- **No real company's data in this repository — structural, not procedural.** Real company bundles live
+  in an external store (`CLEAROTRON_CUSTOMERS_DIR`/`CLEAROTRON_INSTRUCTIONS_DIR`); the repo ships synthetic demo
+  companies only. Run data lives in operator-owned directories outside git (`CLEAROTRON_REPORTS_DIR`,
   workspace root, outbox), backed up by the operator, never committed.
 - Secrets enter only via environment (`.env` on the host); the repo carries `.env*.example` files
   with placeholders. CI runs a secret scan (gitleaks) on every push.
@@ -166,12 +166,12 @@ no messages and holds no channel credentials.
 
 ## Prompt-injection posture
 
-- Client-facing tool outputs carry context-phrased guidance (not imperatives) so MCP metadata
-  scrubbers pass them through, and the client pack tells the assistant to relay the report's own
+- Tool outputs a company's assistant receives carry context-phrased guidance (not imperatives) so MCP
+  metadata scrubbers pass them through, and that assistant's pack tells it to relay the report's own
   wording and never to invent a finding, level, jurisdiction or source
   (`skills/clearotron-client/SKILL.md`). What no pack yet says is that report content is DATA rather
   than instructions: nothing in the prompt payload answers an instruction embedded in a report, so on
-  the client side that output note is the whole of this control today.
+  that side the output note is the whole of this control today.
 - The courier contract is **verbatim relay** — an integrator agent following the ops pack never
   executes instructions found inside packets, it transports them.
 

package/docs/architecture/01-product-overview.md

@@ -11,7 +11,8 @@ never as the orchestrator.
 ## What it does
 
 **Who this is for.** Anyone who needs to know whether a name is free to use and is willing to run the
-search themselves: a lawyer, a brand team, or an individual clearing their own mark. You need three
+search themselves: a company clearing its own names, a lawyer clearing them for the companies they act
+for, or an individual clearing their own mark. You need three
 self-serve accounts: a reasoning CLI, a register, and web research.
 
 **What you get.** Four searches at different depths. A knockout screens up to eight names in minutes.
@@ -40,7 +41,7 @@ Every completed matter is a self-contained run directory plus a published delive
 
 | Artifact | What it is | Consumer |
 |---|---|---|
-| **Clearance report** (HTML) | The deliverable: verdict, four reads, rated findings, coverage statement, actions. Client-formatted via the profile layer. | The client, via the vetting lawyer |
+| **Clearance report** (HTML) | The deliverable: verdict, four reads, rated findings, coverage statement, actions. Formatted for the company via the profile layer. | The company, via the vetting lawyer |
 | **Audit workbook** (Excel) | Every finding — including deliberately excluded noise — with its written reasoning and source record. Built by pure code from the findings spine. | The vetting lawyer; diligence |
 | **Receipts** | Pre-delivery lint, coverage ledger (prose + machine JSON), reasoning-integrity receipt, provider-usage ledger, token rollup. | Operators; auditors |
 | **Decision trace** | Append-only event stream of every stage, retry, gate action, escalation, and delivery step (`_driver/run.jsonl`). | Operators; auditors |
@@ -59,11 +60,11 @@ flowchart LR
     C --> D["Challenge<br/>the draft"]
     D --> E["Deliver the<br/>decision"]
 
-    A -.- a2["Email in; matter, client,<br/>scope, deadline resolved"]
+    A -.- a2["Email in; matter, company,<br/>scope, deadline resolved"]
     B -.- b2["Registers + live marketplace,<br/>worldwide; depth follows risk"]
     C -.- c2["Legal / commercial / risk / impact —<br/>separated to the last page"]
     D -.- d2["Independent review +<br/>blind re-derivation"]
-    E -.- e2["Client's framework and format;<br/>lawyer vets, then it moves"]
+    E -.- e2["The company's framework and format;<br/>lawyer vets, then it moves"]
 
     classDef phase fill:#1a3a5c,stroke:#4a90d9,color:#fff
     classDef note fill:none,stroke:none,color:#888,font-size:12px
@@ -79,17 +80,17 @@ The full stage-by-stage mechanics — fan-out, barriers, gates, escalation and r
 Risk is never one blended number. Every matter carries four separated reads, kept apart from the
 first reasoning stage to the final page of the report:
 
-- **Legal read** — would a claim succeed? Client-independent: the same conflict gets the same
-  legal read for every client.
+- **Legal read** — would a claim succeed? Company-independent: the same conflict gets the same
+  legal read for every company.
 - **Commercial read** — would this opponent actually fight, and what kind of fight: a classic
   infringement battle, a negotiation, a paper conflict with a dormant registration, or nuisance?
 - **Risk read** — how likely the conflict becomes a real problem, all told.
-- **Impact read** — what a fight would mean for *this* client, industry, and launch. The one read
-  where the client's world properly enters the analysis.
+- **Impact read** — what a fight would mean for *this* company, industry, and launch. The one read
+  where the company's world properly enters the analysis.
 
 The separation is engineered, not stylistic: the profile layer can shape emphasis, vocabulary, and
 format, but configuration that attempts to move a legal rating is rejected by the system itself
-(the anti-threshold guard — see [05 — Customer profiles](05-customer-profiles.md)).
+(the anti-threshold guard — see [05 — Company profiles](05-customer-profiles.md)).
 
 ## The disciplines that make it a product
 
@@ -99,7 +100,7 @@ mechanism in the code, not a policy statement — the pointers go to the chapter
 | Discipline | Mechanism | Documented in |
 |---|---|---|
 | Judgment encoded, not rules | Doctrine as prose methodology (skills) reasoned by the judgment tier; hard ceilings in a locked rating framework | [08](08-development-guide.md), [05](05-customer-profiles.md) |
-| Clients drive the deliverable, never the analysis | Profile layer with closed key enum + anti-threshold guards + stage-level firewall; framework manifests carry vocabulary only, never rules (CI-linted) | [05](05-customer-profiles.md) |
+| Companies drive the deliverable, never the analysis | Profile layer with closed key enum + anti-threshold guards + stage-level firewall; framework manifests carry vocabulary only, never rules (CI-linted) | [05](05-customer-profiles.md) |
 | Four reads, never one number | Findings model carries the reads separately; report templates render them separately | [07](07-quality-and-audit.md) |
 | It knows what to leave out | Below-threshold exclusions keep their written reasoning in the audit workbook | [07](07-quality-and-audit.md) |
 | Crowding must be earned | A crowded-field mitigation requires the counted, filtered field on the record | [07](07-quality-and-audit.md) |
@@ -111,7 +112,7 @@ mechanism in the code, not a policy statement — the pointers go to the chapter
 Beneath all nine sit two engineering properties: **judgment on rails** (the deterministic pipeline,
 [02](02-architecture.md)) and **a memory that keeps it honest** (the reference library and replay
 harness every change to the system's thinking is re-tested against — a discipline someone runs by hand,
-not a mechanism: the replay corpus is real client matter on the machine that holds it, invoked from the
+not a mechanism: the replay corpus is real clearance data on the machine that holds it, invoked from the
 command line, the reference library is a paid A/B, and neither is in `npm test` or in CI,
 [07 §7](07-quality-and-audit.md#7--the-memory-that-keeps-it-honest)).
 
@@ -120,9 +121,9 @@ command line, the reference library is a paid A/B, and neither is in `npm test`
 - The driver runs as systemd `--user` units of one service account (no root units), entirely
   outside any agent sandbox. Where an integrator agent platform is deployed beside it (the
   reference integration), those agents have `exec` denied and can only write queue files.
-- Per-customer behaviour is configuration, never a fork: every deployment runs the same engine and
-  customers differ only in their profile bundles ([05](05-customer-profiles.md)). Client identities
-  are not named here.
+- Per-company behaviour is configuration, never a fork: every deployment runs the same engine and
+  companies differ only in their profile bundles ([05](05-customer-profiles.md)). No real company is
+  named here.
 - Wall-clock per matter is on the order of several hours — an operational measurement, not a specification:
   deliberate sequencing and provider pacing, with model compute a fraction of it. Stage timeout
   budgets in [04](04-configuration-reference.md) bound the components.
@@ -154,8 +155,8 @@ Terms used throughout this pack and the code. The code's names win over prose de
 | **Sentinel** | An on-disk marker file that makes an action idempotent (e.g. `.published`, `.sent`). |
 | **Sidecar** | A small metadata file next to a primary artifact (e.g. claimer pid next to a claimed job). |
 | **Slug / codename** | Run-directory naming: deterministic slug plus a generated `adjective-noun` codename. |
-| **Profile bundle** | A customer's git-owned configuration: structural config, context pack, delivery style, framework. |
-| **Context pack** | The client-knowledge layer fed to reasoning as context — sharpens judgment, never overrides it. |
+| **Profile bundle** | A company's git-owned configuration: structural config, context pack, delivery style, framework. |
+| **Context pack** | What the engine knows about the company, fed to reasoning as context — sharpens judgment, never overrides it. |
 | **Doctrine** | The encoded legal method: the skills prose, rating framework, and worked examples. |
 | **Reference library** | Lawyer-blessed verdicts on real matters; every change to the thinking is re-tested against it. |
 | **Replay harness** | The $0 pure-file re-run over archived runs; catches structural regressions, not reasoning drift. |

package/docs/architecture/02-architecture.md

@@ -25,14 +25,14 @@ these.
    and it is architectural, not a tuning knob.
 4. **Fail loud, fail closed, repair first.** Every failure has a class in a closed taxonomy with
    distinct handling; bounded repairs (warm patches, code re-dispatch, quarantines) run before any
-   retry burns a fresh session; gates that protect the client (client gate, coverage terminals)
+   retry burns a fresh session; gates that protect the reader (client gate, coverage terminals)
    fail closed; and a run that dies tells the operator on the same guaranteed lane as delivery.
 5. **The quality floor never falls back.** Only transient-infrastructure failures may retry or
    fall over; a content or coverage defect never gets handed to a weaker model or waved through.
 6. **Configuration is layered and frozen per run.** Environment variables tune mechanics; profile
-   bundles carry per-customer knowledge; both are resolved once at run start and frozen into the
+   bundles carry per-company knowledge; both are resolved once at run start and frozen into the
    run dir. A run's behaviour is fully explained by its own directory.
-7. **Tokens, not dollars.** The driver accounts model usage in tokens only. Cost arithmetic is the
+7. **Tokens, not dollars.** The driver counts model usage in tokens only. Cost arithmetic is the
    provider's business; the driver's job is attribution.
 
 ## The two substrates
@@ -56,7 +56,7 @@ flowchart TB
         GWM["gateway.mjs — runStage()<br/>retry ladder · file-truth gate · fail taxonomy"]
         ENG["engine seam (CLEAROTRON_AI)<br/>anthropic-agent (default) | openai-agent"]
         SKL["skills/ — stage methodology (doctrine)"]
-        PROF["profiles/ — per-customer bundles"]
+        PROF["profiles/ — per-company bundles"]
         PUB["publish/ — report · audit workbook · pool"]
         RUN --> PIPE --> GWM --> ENG
         STG --> GWM
@@ -276,7 +276,7 @@ All paths relative to [`driver/`](../../driver/). The load-bearing seven are mar
 | `phase0.mjs` | Pure run identity: slug, codename, dates, run/archive dirs. |
 | `enqueue-schema.mjs` | Job-file shape, `validateJob` classification (reject/clarify/run). |
 | `slot-lock.mjs` | Cross-process counting locks (run slots, turn/ping lanes). |
-| `profiles.mjs` · `profiles/` · `framework.mjs` | Per-customer layer: bundle resolution, freeze, rating framework. [05](05-customer-profiles.md). |
+| `profiles.mjs` · `profiles/` · `framework.mjs` | Per-company layer: bundle resolution, freeze, rating framework. [05](05-customer-profiles.md). |
 | `coverage-ledger.mjs` | Coverage-ledger contract: strict JSON mirror, prose parser, axes decisions. |
 | `findings-model.mjs` | The findings spine: structure, validation, consolidation. |
 | `registry-fidelity.mjs` | Record grounding: citation closure, identifier auto-correction from records. |
@@ -306,5 +306,5 @@ For a buyer: these are the exact surfaces to re-point, and nothing else.
 | **Out** | Published report (templated HTML) + Excel audit workbook + receipts in the pool | [07](07-quality-and-audit.md) |
 | **Out** | Delivery packet (`_driver/delivery.json`: composed email HTML, chat text, URL, verdict) + outbox wake marker | [03 §4](03-run-lifecycle.md) |
 | **Out** | Failure packet on the same lane (`_driver/failure.json`) | [03 §5](03-run-lifecycle.md) |
-| **Sideways** | Artifacts MCP read layer (runs, findings, traces, briefs; scoped client tokens) — effectively the product API | [07](07-quality-and-audit.md), [09](09-security-and-data.md) |
+| **Sideways** | Artifacts MCP read layer (runs, findings, traces, briefs; scoped `user` and `account` tokens) — effectively the product API | [07](07-quality-and-audit.md), [09](09-security-and-data.md) |
 | **Providers** | Model engine seam (`engine/CONTRACT.md`) · register-provider seam (`activeProvider()`) | above; [08](08-development-guide.md) |

package/docs/architecture/03-run-lifecycle.md

@@ -85,7 +85,7 @@ intake AI, and classifies rather than just rejecting:
 | `run` | Good to go | warnings may note proceed-with-default choices |
 
 Warnings never block: a missing TMP reference produces a `noref` slug instead of a silent reject;
-an unknown customer proceeds on the generic profile with a late-bind watch (§4).
+an unknown company proceeds on the generic profile with a late-bind watch (§4).
 
 **Matter-level dedup** (`runner.mjs`). Queue-file dedup is per *message*; a "please
 proceed" reply in an already-handled thread arrives under a new message-id. The driver therefore
@@ -94,7 +94,7 @@ job within the window (a fixed 24 hours) that matches a prior entry by
 exact signature (`forwarder|mark|classes|customer|ref`, plus a `|level:<product>` dimension on any
 non-baseline product) or by same conversation-thread with agreeing mark *and* agreeing product. The
 product dimension is why a knockout→clearance escalation of one matter — same forwarder, mark,
-classes, customer and ref — is never parked as a duplicate; that escalation is the offering's
+classes, company and ref — is never parked as a duplicate; that escalation is the offering's
 headline flow. Three distinct marks forwarded in one thread all run; a forced re-run is
 `dupOverride: true` in the job. Failed runs drop their ledger entry so a genuine re-send is never
 blocked.
@@ -284,7 +284,7 @@ Reading order for the phases, with what code decides at each:
     **verdict sidecar** (`_driver/verdict.json`) then becomes the single verdict authority for
     everything downstream; failing to write it is fatal.
 14. **Delivery phase** — report overview (fatal), per-finding report cards (fan-out, individually
-    non-fatal, assembled by code with a code-built "Only you can close these" section), client
+    non-fatal, assembled by code with a code-built "Only you can close these" section), the
     audit workbook from the findings spine (code, count-guarded, non-fatal), then the pre-delivery
     lint block: registry-record closure (every cited register URI owes a fetched record — absentees
     are code-fetched), lint checks, registry identifier auto-correction *from the record*, one warm
@@ -302,10 +302,10 @@ coverage terminal, the core-artifact gate, and the client gate. *Note-and-contin
 and enrichment (blind-frame, frame-diff/reopen, skeptic, case-law, per-card renders, audit build,
 closure passes, receipts, rollups, notify). An outage in a checker never destroys completed gather work.
 
-**One report, no client fork.** There is no separate client-facing summary artifact and no stage
-that writes one: a live run produces one report, and what a non-staff reader receives is prepared at
+**One report, no second version.** There is no separate summary artifact for outside readers and no
+stage that writes one: a live run produces one report, and what a non-staff reader receives is prepared at
 serve time from it. The lint checks and validators that used to cover a second surface are kept so
-archived runs still replay unchanged, but a live run passes them nothing. The report a client reads
+archived runs still replay unchanged, but a live run passes them nothing. The report a company's people read
 is guarded by the code-built verdict-bound row, the pre-delivery lint, and the client gate.
 
 ## 4 — Delivery handoff
@@ -322,7 +322,7 @@ any notify, and both halves are idempotent.
   50-minute rescan is the backstop. A lost wake can delay a send; it can never lose or double-send
   one — the deliverer re-derives everything from the packet and the sentinels.
 
-**Late-bind** deserves a note: a job forwarded for an unknown customer runs on the generic profile
+**Late-bind** deserves a note: a job forwarded for an unknown company runs on the generic profile
 with four code checkpoints (`pre-matter-frame`, `pre-digest`, `pre-synthesis`, `pre-delivery`)
 polling for a `customer-bind.json` dropped by the operator; each checkpoint applies the strongest
 still-safe action its phase allows (`lateBindAction`: fold the job, ride the digest message,