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

package/docs/architecture/07-quality-and-audit.md

@@ -26,7 +26,7 @@ flowchart LR
     G["GROUNDED<br/>records behind every fact"] --> C["CHALLENGED<br/>skeptic + blind pass +<br/>independent reviewer"]
     C --> K["COMPLETED<br/>coverage honesty,<br/>clamps, no dangling caveats"]
     K --> F["IN FRONT<br/>lawyer vets the<br/>defended draft"]
-    F -.-> I["INTERROGABLE<br/>read-only audit API,<br/>per-run client tokens"]
+    F -.-> I["INTERROGABLE<br/>read-only audit API,<br/>per-run report-link tokens"]
 ```
 
 ## 1 — Grounded: record fidelity (`registry-fidelity.mjs`, `findings-model.mjs`)
@@ -162,15 +162,15 @@ one. Calls are metered per run (billing-grade ledger), never hard-capped.
 ## 4 — The pre-delivery lint (`predelivery-lint.mjs`)
 
 Pure code over the assembled deliverable surfaces before anything outward-facing. On a live run
-those are the report and the composed email: there is no second client-facing artifact, and the
-lint's client-summary arms are kept only so the archived corpus still replays.
+those are the report and the composed email: there is no second artifact for outside readers, and
+the lint's arms for the retired `clientSummary` are kept only so the archived corpus still replays.
 
 Thirty-three check families (`runLint` fans out to that many `*Checks` groups; the coarser `family`
 label stamped on each emitted check collapses them to 14): template integrity, orphan-reference
 precision, machine-work reachability ("Only you can close these" must contain only things genuinely
-client-side), counting consistency across surfaces and against the findings set, the registry
+left to the company), counting consistency across surfaces and against the findings set, the registry
 family (§1), finding-provenance cross-contamination, correction consistency (a review-withdrawn
-finding can never resurrect on any surface), client-tier and overall-tier joins, verdict/actions
+finding can never resurrect on any surface), the `client-tier-match` and overall-tier joins, verdict/actions
 coherence, intake-ask completion, WIPO designation language, self-comparison.
 
 Repair economics are engineered: failing checks on a drafting surface get one bounded warm redo
@@ -186,8 +186,8 @@ pass over inherited artifacts is visible as such.
 | Severity | Trigger |
 |---|---|
 | **Fails the run** | Zero readable coverage-ledger rows (the coverage-honesty floor cannot run, so no verdict can ship); core findings artifact unparseable after corrective retries; the fatal stages/gates in [03](03-run-lifecycle.md). Two things a reader expects here are **not**: an unresolved screen-gate repairs or discloses and never blocks (a per-mark coverage row + the CONDITIONAL clamp, disclosed in `_driver/screen-gate-unresolved.json` — owner decision 2026-07-22, never a dead run over a provider 404), and the client gate blocks nothing (next row) |
-| **Recorded by the client gate, blocks nothing** (the gate's preflight was removed with the readiness state it chose — `pipeline.mjs`) | `evaluateClientGate` still runs its machine checks inside `publishReport` — registry arithmetic, record fidelity, correction consistency, unparseable/quarantined findings, stale corrections, failed escalations (`publish/index.mjs`, fail-closed: an evaluation error also closes). Its result lands on the audit workbook, `meta.json` and the machine-qc-failed telemetry event. **It decides nothing about who may read**, and there is no client export to withhold — a defect that changes the LEGAL ANSWER is the verdict clamp's job and rides the report as a CONDITIONAL/BLOCKING verdict, never as a warning about the document |
-| **Flags, never blocks** | Everything else — recorded in the `_driver` receipt sinks and surfaced on the audit workbook / quality pages; **the rendered report carries no caveat banner** (the report a lawyer signs is clean; the receipts are the QC surface). Lint flags also never ride `report.md` front-matter (that file is copied verbatim to the client-reachable pool; a front-matter flag was a latent client leak) |
+| **Recorded by the client gate, blocks nothing** (the gate's preflight was removed with the readiness state it chose — `pipeline.mjs`) | `evaluateClientGate` still runs its machine checks inside `publishReport` — registry arithmetic, record fidelity, correction consistency, unparseable/quarantined findings, stale corrections, failed escalations (`publish/index.mjs`, fail-closed: an evaluation error also closes). Its result lands on the audit workbook, `meta.json` and the machine-qc-failed telemetry event. **It decides nothing about who may read**, and there is no separate export to withhold — a defect that changes the LEGAL ANSWER is the verdict clamp's job and rides the report as a CONDITIONAL/BLOCKING verdict, never as a warning about the document |
+| **Flags, never blocks** | Everything else — recorded in the `_driver` receipt sinks and surfaced on the audit workbook / quality pages; **the rendered report carries no caveat banner** (the report a lawyer signs is clean; the receipts are the QC surface). Lint flags also never ride `report.md` front-matter (that file is copied verbatim to the pool outside readers reach; a front-matter flag was a latent leak to them) |
 
 ## 5 — Observability that refuses to be a gate
 
@@ -221,7 +221,7 @@ verdict, clamp, delivery event), per-attempt telemetry (`_driver/<stage>.jsonl`
 class, kill signals, token usage), the fetched records themselves (`_records/`, receipts indexed in
 `_driver/receipts.json`), and the receipt set ([03 §7](03-run-lifecycle.md#7--run-directory-anatomy)
 maps all of it). The provider-usage ledger tallies billable register calls per run (billing-grade:
-counts, retries, errors, cache hits, duplicate-fetch splits), and the token rollup accounts every
+counts, retries, errors, cache hits, duplicate-fetch splits), and the token rollup counts every
 attempt including retry waste — tokens only, no currency, by directive.
 
 ## 7 — The memory that keeps it honest
@@ -230,12 +230,12 @@ Three layers, from cheapest to most authoritative:
 
 1. **The $0 replay harness** (`replay-archive.mjs`): re-runs every validator and the lint over the
    archived corpus and diffs against a snapshot; any verdict-string flip fails (exit 2). Nothing in
-   `.github/workflows/` runs it, and a hosted runner could not: the corpus is real client matter that
+   `.github/workflows/` runs it, and a hosted runner could not: the corpus is real clearance data that
    stays on the machine holding it, and the snapshot lives outside the git tree. So the gate is a
    hand-run convention — `--update` on main, diff on the candidate, every flip an intended fix.
    Catches structural/validator regressions; cannot see reasoning drift.
 2. **Gate metrics on holdout runs** (`gate-metrics.mjs`): deferral rendering, skeptic consumption,
-   scored-finding grounding, client-tier match, lint first-pass tax — a fix is accepted only if the
+   scored-finding grounding, `clientTierMatch`, lint first-pass tax — a fix is accepted only if the
    metrics move on runs it never cited.
 3. **The reference library**: lawyer-blessed verdicts on real matters, re-run in a **paid A/B**
    for any grade-moving change, read against the system's measured run-to-run wobble (the
@@ -261,7 +261,7 @@ write nothing and 7 that do:
   `get_provider_usage` (recomputed live from the billing ledger, with drift detection),
   `get_coverage`, `search`, `decision_timeline`, `run_changes` (stable-cursor change feed),
   `diff_artifact` (with diff-ref whitelisting that closes cross-run path escapes), and
-  `get_delivery_packet` (the run's send payload; never exposed to client tokens).
+  `get_delivery_packet` (the run's send payload; never exposed to `user` or `account` tokens).
 - **Read, cross-run** — `list_runs`, `search_runs`, `list_profiles`, `list_outbox_events`, plus the
   two free pre-order reads `describe_options` and `plan_run`, which resolve what a search *would* do
   without reserving, spending or queueing anything.
@@ -269,22 +269,22 @@ write nothing and 7 that do:
   `what_if_run` → one sandboxed stage; `what_if_result` → collect a queued one) — **executing** is
   local stdio only, never remote, for any principal. The confirmation token is a deliberate-action
   handshake, not a crypto boundary; the security boundary is ops scope + local-only execution.
-  Since the owner's 2026-08-27 ruling a client ACCOUNT reaches all three, and `what_if_run` on that
+  Since the owner's 2026-08-27 ruling an `account` principal reaches all three, and `what_if_run` on that
   path ENQUEUES into `<runDir>/_experiments/_queue/` rather than shelling — `driver/whatif-worker.mjs`,
-  drained by the runner, is what spawns the sandbox. Because the token is unsigned, a client call must
-  also name its `runId` so the account gate fires, and the enqueue refuses a token naming another run.
+  drained by the runner, is what spawns the sandbox. Because the token is unsigned, a call on that path must
+  also name its `runId` so the grant check fires, and the enqueue refuses a token naming another run.
 - **5 ops write verbs** (`start_run` — validated atomic enqueue; `stop_run` — real cancel before
   claim, best-effort sentinel after; `feed_context`; and the integrator write-backs `ack_event` and
   `mark_sent`, which refuses to settle a send without a messageId or an explicit attestation) — ops
   scope only, never on the public connector.
 
 One run = one self-auditing directory; the read layer adds no state of its own — it projects the
-run dir and the ledgers. The auth model (four principal kinds; run-bound client tokens reaching
+run dir and the ledgers. The auth model (four principal kinds; run-bound `user` tokens reaching
 exactly `brief`, `read_artifact` gated to the report, and `list_findings` gated to the curated card
 groups) is documented in [09 — Security and data](09-security-and-data.md).
 
-**A signed-in client account reads the audit chain** (ruling 2026-08-27). The audit trail is
-what makes a clearance defensible, and the person who has to defend the filing is the client's
+**A signed-in `account` principal reads the audit chain** (ruling 2026-08-27). The audit trail is
+what makes a clearance defensible, and the person who has to defend the filing is the company's
 lawyer — so `audit`, `narrative`, the record artifacts and a register axis are readable through
 `read_artifact`, the raw `list_findings` path returns the AT#/F#/NR# records, and `get_run`, `trace`
 and `decision_timeline` walk the decision chain. What stays internal is not the chain but the cost

package/docs/architecture/08-development-guide.md

@@ -68,7 +68,7 @@ These are the things a well-meaning refactor breaks. Each is enforced somewhere;
    (+ `stallSec` **strictly less than** the timeout for any stage whose first action can stream
    nothing — a long tool call looks like a stall), `out(paths)` (absolute path via `paths()`),
    `validate`, and the `message(ctx)` with its `reads([...])` (the *live* skill reads —
-   `skillReads:` is declarative metadata only; do not "reconcile" them, per-customer framework
+   `skillReads:` is declarative metadata only; do not "reconcile" them, per-company framework
    selection depends on the difference).
 2. **Write its validator** in `verify.mjs` — lenient enough never to false-fail a valid leaf,
    strict on truncation/emptiness/wrong-stage output. If it needs run context, read the frozen
@@ -225,8 +225,8 @@ Four realities to respect:
 - **The `||=` env guards leak**: a shell exporting a real register credential or
   `CLEAROTRON_PLAN_DISPATCH=on` is *not* overridden by the harness — run the suite in a clean env.
   (CI is safe.)
-- **A skipped guard is not a passed guard.** Several checks enumerate every tracked file (no client
-  identifier, no operator identity, no citation of a path the public tree will not carry, every env
+- **A skipped guard is not a passed guard.** Several checks enumerate every tracked file (no real
+  company's identifier, no operator identity, no citation of a path the public tree will not carry, every env
   var written down) and can only do that off a git checkout; off a source zip they skip by name.
   CI asserts both that no guard printed `[repo-guard] SKIPPED` *and* that at least one printed
   `[repo-guard] ok` — the second half matters, because "no SKIPPED line" also passes on an empty log.

package/docs/architecture/09-security-and-data.md

@@ -14,7 +14,7 @@ them, by inheritance, never by file-copy into configs.**
 flowchart TB
     subgraph INET["Internet"]
         U["Staff (browser)"]
-        CLI["Client AI agents<br/>(interrogation)"]
+        CLI["Company AI agents<br/>(interrogation)"]
         EXT["Model provider · registries ·<br/>research/case-law APIs"]
     end
     subgraph EDGE["Auth proxy + tunnel<br/>(this deployment: Cloudflare)"]
@@ -67,35 +67,35 @@ are no root units; everything is `systemd --user`.
   codebase: trusted local **stdio** (full tool set — trust boundary is the right to exec the
   binary), a **staff HTTP** face (loopback :18790 behind Tunnel + Access), and a **client HTTP**
   face (loopback :18811) that is a *separate process* with a *different Access audience* — "a
-  client can never reach internal read-all" is a configuration fact, not a runtime branch (startup
+  company's person can never reach internal read-all" is a configuration fact, not a runtime branch (startup
   refuses if the two AUDs are equal). Auth is two-layered and fail-closed:
   - **Outer**: the CF Access JWT is re-verified at origin on every request — RS256 pinned, issuer
     + audience checked, expiry required, email claim must be a real string (array-claim smuggling
     rejected), domain matched exactly on the final `@` (subdomain look-alikes rejected).
   - **Inner**: HMAC-signed scope tokens (`v1.<payload>.<sig>`, timing-safe compare, fail-closed
     without the secret, default TTL 30 days). Four principal kinds, resolved by `visibleTools()` and
-    `authorize()` in `shared/scope.mjs`: **ops** (stdio, or ops token
-    over staff HTTP — reads + ops verbs; what-if only when local), **internal** (verified
-    firm-domain staff — all 23 non-write tools, no writes), **user** (run-bound token minted into the
+    `authorize()` in `shared/scope.mjs`: **`ops`** (stdio, or ops token
+    over staff HTTP — reads + ops verbs; what-if only when local), **`internal`** (verified
+    staff at your own domain — all 23 non-write tools, no writes), **`user`** (run-bound token minted into the
     report's "Ask your AI" link — exactly `brief` + `read_artifact` gated to the report (there is
     one report, and the link block is staff-only at serve time) + `list_findings`
     gated to curated groups, pinned to one run; filter args that could reach internal methodology
-    are stripped), and **account** (a signed-in customer on the client face — their granted
-    accounts' runs, reached either by the CF sign-in with no token, or by a per-person API key,
-    `scope: account`, whose accounts are re-read from the grants file on every request rather than
+    are stripped), and **`account`** (a signed-in person on the client face — the runs of the
+    companies they are granted, reached either by the CF sign-in with no token, or by a per-person API
+    key, `scope: account`, whose companies are re-read from the grants file on every request rather than
     baked into it. Wider *reach* than a report link and, since the owner's 2026-08-27 ruling, more
     *depth* too: the audit chain — the audit trail, the reasoning narrative, the record artifacts, a
     register axis, and the `get_run` / `trace` / `decision_timeline` decision walk. Model identity
     and billed counts stay sealed (`get_telemetry`, `get_provider_usage`), as does the reviewers'
     critique of the engine's own output; the chain's prose goes through the report's own
-    client-safety passes in `mcp-server/lib/audit-view.mjs`, and the artifact set is its own
+    scrub passes in `mcp-server/lib/audit-view.mjs`, and the artifact set is its own
     `ACCOUNT_ARTIFACTS` so that widening it never widens the forwardable report link. The same ruling
     opened WHAT-IF, and on this face it queues rather than shells: `what_if_run` writes a job into the
     run's own `_experiments/_queue/` and `driver/whatif-worker.mjs` spawns the sandbox from a service
-    process, so no remote face executes the engine. The confirmation token is unsigned, so a client
-    call must also name its `runId` — the account gate keys on that, and the enqueue refuses a token
+    process, so no remote face executes the engine. The confirmation token is unsigned, so a call on
+    this face must also name its `runId` — the grant check keys on that, and the enqueue refuses a token
     naming a different run).
-    Scope resolution is positive: no token and not firm
+    Scope resolution is positive: no token and not
     staff ⇒ 403 — the old silent default-to-internal was a real bug, now regression-pinned.
     The API-key door is a fourth process (loopback :18812) with **no Access in front** — the trade is
     explicit: a mandatory key replaces the browser sign-in, and the mode refuses to start if anything
@@ -120,12 +120,12 @@ from the repository root; the rest are relative to `driver/`.
 
 | Destination | What is sent | Code |
 |---|---|---|
-| **The reasoning provider** — `api.anthropic.com` through the Claude CLI, or OpenAI through the Codex CLI | The whole matter: the mark and its variants, the Nice classes, the goods and services wording, the jurisdictions, the requester and forwarding fields of the job file, the customer profile and risk framework the stage reads, the register records already fetched, and every prior stage's artifact | `engine/anthropic-agent.mjs` spawns `claude`; `engine/openai-agent.mjs` spawns `codex`. **The CLI opens the connection — no driver code calls the provider.** Subscription mode deletes `ANTHROPIC_API_KEY` from the child environment (`anthropic-agent.mjs`) |
+| **The reasoning provider** — `api.anthropic.com` through the Claude CLI, or OpenAI through the Codex CLI | The whole matter: the mark and its variants, the Nice classes, the goods and services wording, the jurisdictions, the requester and forwarding fields of the job file, the company profile and risk framework the stage reads, the register records already fetched, and every prior stage's artifact | `engine/anthropic-agent.mjs` spawns `claude`; `engine/openai-agent.mjs` spawns `codex`. **The CLI opens the connection — no driver code calls the provider.** Subscription mode deletes `ANTHROPIC_API_KEY` from the child environment (`anthropic-agent.mjs`) |
 | **`api.perplexity.ai/v1/agent`** | The mark and its variants, the goods wording, and the marketplace, dictionary, and meaning probes. The driver writes the grid spec and dictates every cell; the model does not compose the sweep | `providers/perplexity/src/core.js`. On a clearance the `common-law`, `common-law-half`, and `synthesis` stages hold it through `engine/mcp/perplexity-server.mjs` (`engine/mcp/gather-config.mjs`); on a knockout the code-side sweep calls the adapter directly (`pipeline-knockout.mjs`), and with no `PERPLEXITY_API_KEY` that call is never made — the screen skips the sweep and discloses it, so nothing on this row leaves the box |
 
 **The one register you configure.** The `register-unit` stages send the mark string, its generated
 variants, the Nice classes, office filters, and record ids for fetches. They do not send the requester,
-the client name, the goods description, or any profile material.
+the company's name, the goods description, or any profile material.
 
 | `CLEAROTRON_DATABASE` | Host | Code |
 |---|---|---|
@@ -189,32 +189,32 @@ stylesheets above.
   non-secret attribution values (session key for usage attribution, agent id) ride the config.
 - **Register credentials are preflighted** at run start and resume — a missing credential fails
   fast before any model spend, never mid-run or at delivery.
-- **Git-side hygiene**: profiles and their audit log are tracked (client-identifying — see below);
+- **Git-side hygiene**: profiles and their audit log are tracked (they identify real companies — see below);
   the replay snapshot deliberately lives *outside* the git tree because it holds mark names; and
-  the driver's `.gitignore` blocks run-directory shapes so a stray run dir (client matter data) can
+  the driver's `.gitignore` blocks run-directory shapes so a stray run dir (real clearance data) can
   never be swept into a backup commit.
 
 ## Data classes and where they live
 
 | Class | Locations | Notes |
 |---|---|---|
-| **Client matter data** | queue files + prose sidecars; run dirs; archive tree; publish pool; outbox packets | The crown jewels. Runs are per-agent-workspace; the pool is the only web-reachable copy (Access-gated, group-readable 0640) |
+| **Clearance data** | queue files + prose sidecars; run dirs; archive tree; publish pool; outbox packets | The crown jewels. Runs are per-agent-workspace; the pool is the only web-reachable copy (Access-gated, group-readable 0640) |
 | **Registry records** | `_records/`, telemetry ledgers | Licensed provider data — contract terms govern retention/transfer at handover |
-| **Doctrine** | `skills/`, framework decks, worked examples | The asset; transfers under the definitive agreement. Worked examples derive from real matters — treat as client-adjacent |
-| **Customer profiles** | `profiles/*.json`, context packs, `_audit.log` | Client-identifying by design (names, own brands, competitor lists) — the reason this *pack* names no clients |
-| **Reference library / calibration corpus** | outside the repo | Built on real client matters — **confidential client material, not freely transferable IP**; transfer needs a client-consent/sanitization plan |
+| **Doctrine** | `skills/`, framework decks, worked examples | The asset; transfers under the definitive agreement. Worked examples derive from real matters — treat them as close to real company data |
+| **Company profiles** | `profiles/*.json`, context packs, `_audit.log` | They identify real companies by design (names, own trading names, competitor lists) — the reason this *pack* names none |
+| **Reference library / calibration corpus** | outside the repo | Built on real clearances — **confidential company material, not freely transferable IP**; transfer needs a consent and sanitization plan agreed with those companies |
 | **Telemetry** | `~/trademark/telemetry/*.jsonl` (a box upgraded across the move keeps the pre-change telemetry directory — resolved by existence, oldest first),`_driver/*.jsonl` | Billing-grade provider usage + attempt telemetry; append-only; no automated retention |
 
-**Posture commitments** (engineering-true, restated from the outward materials): no client data
-trains any model; each client's context is isolated in its profile bundle and frozen per run;
-privileged-and-confidential handling is a per-client delivery flag; and there is no separate
-client-facing export to keep in step — one report, with what a non-staff reader
-receives prepared at a single serve-time chokepoint (`driver/portal-report.mjs`) and the MCP client
-cut composed from the same driver transforms rather than restating them
+**Posture commitments** (engineering-true, restated from the outward materials): no company's data
+trains any model; each company's context is isolated in its profile bundle and frozen per run;
+privileged-and-confidential handling is a per-company delivery flag; and there is no separate
+export for outside readers to keep in step — one report, with what a non-staff reader
+receives prepared at a single serve-time chokepoint (`driver/portal-report.mjs`) and the client
+face's cut composed from the same driver transforms rather than restating them
 ([07 §4](07-quality-and-audit.md#4--the-pre-delivery-lint-predelivery-lintmjs)).
 
 **Retention** is currently append-forever everywhere (runs, archive, pool, ledgers). That is a
-deliberate audit-trail choice, but it means data-subject or client-offboarding requests are manual
+deliberate audit-trail choice, but it means data-subject or company-offboarding requests are manual
 today — flag for the buyer's compliance review.
 
 ## Supply chain and dependency posture

package/docs/architecture/README.md

@@ -12,7 +12,7 @@ that" question, or when you are changing something and need to know what depends
 | [`03-run-lifecycle.md`](03-run-lifecycle.md) | One run from intake to delivered packet — every stage, gate and resume point |
 | [`04-configuration-reference.md`](04-configuration-reference.md) | Every environment variable, what reads it, and what unset means |
 | [`05-config-governance.md`](05-config-governance.md) | The rules configuration obeys: who may add a name, and the drift classes |
-| [`05-customer-profiles.md`](05-customer-profiles.md) | The per-customer profile: what it carries and how a run resolves one |
+| [`05-customer-profiles.md`](05-customer-profiles.md) | The per-company profile: what it carries and how a run resolves one |
 | [`06-operations-runbook.md`](06-operations-runbook.md) | Running a deployment — the units, the triggers, and what to do when one wedges |
 | [`07-quality-and-audit.md`](07-quality-and-audit.md) | How the engine proves what it claims: the ledger, the witness, the refutation gate |
 | [`08-development-guide.md`](08-development-guide.md) | Working in the code — the test tiers, the seams, the conventions |

package/docs/branding.md

@@ -4,8 +4,8 @@ Operational guidance, not policy. What you may call your deployment is
 [TRADEMARKS.md](../TRADEMARKS.md); this page is how you change what the software prints.
 
 **Delivering a report that carries somebody else's brand is the failure this page exists to prevent.**
-A clearance report is read by a lawyer and forwarded to a client. If it arrives under a name that is not
-yours, you have built the exact problem the software exists to detect.
+A clearance report is read by the people deciding on a name and forwarded to whoever else must agree. If
+it arrives under a name that is not yours, you have built the exact problem the software exists to detect.
 
 ## What to do instead
 
@@ -19,7 +19,7 @@ install needs no change — but the names below are the ones to write:
 | `CLEAROTRON_BRAND_TAGLINE` | *(empty — no strapline is rendered)* | Report and portal chrome |
 | `CLEAROTRON_BRAND_PRODUCT` | `Trademark clearance` | Artifact naming and connector instructions |
 
-**The defaults name the product, not a firm.** A deployment that sets nothing produces neutrally
+**The defaults name the product, not an organisation.** A deployment that sets nothing produces neutrally
 branded output. That is deliberate: the alternative is what this page warns against, with one
 organisation's name as the path of least resistance. Setting `CLEAROTRON_BRAND_NAME` to your own
 organisation is still the step to take before you deliver anything to anyone.
@@ -30,6 +30,11 @@ renders as **absent** — no element, no stray separator — rather than as a bl
 They are read once, at import (`shared/brand.mjs`), so they are deployment-static: set them in the
 environment file and restart.
 
+`CLEAROTRON_ADMINISTRATOR_CONTACT` is read in the same place and the same way, but it is not a name: it
+is a mail or web address for the person who looks after sign-ins. Preferences tells a signed-in person to
+contact their Clearotron administrator to change their sign-in, and links those words to this contact.
+Unset, the words are plain text.
+
 **Three things that seam does not cover**, stated because finding them at deploy time is worse:
 
 - **The palette is not env-overridable.** Brand colours are defined in code beside those variables.

package/docs/configuration.md

@@ -1,9 +1,9 @@
 # Configuration
 
-*How to configure risk frameworks, registers and markets for your own practice.*
+*How to configure risk frameworks, registers and markets for your own use.*
 
-This is the practice-level guide: which register you search, how risk gets rated, and what the engine
-knows about each client. Environment variables and install-time setup are
+This is the guide to the settings an installation makes its own: which register you search, how risk
+gets rated, and what the engine knows about each company. Environment variables and install-time setup are
 [`../INSTALL.md`](../INSTALL.md); the exhaustive variable table is
 [`architecture/04-configuration-reference.md`](architecture/04-configuration-reference.md).
 
@@ -84,7 +84,7 @@ route, and usually the cheaper one.
 
 ## 2. The risk framework
 
-**The framework in force rates the matter.** A run rates under the client's own framework if one is
+**The framework in force rates the clearance.** A run rates under the company's own framework if one is
 on file, otherwise the Generic default. There is nothing in between and no blending.
 
 A framework is two files that travel together:
@@ -98,8 +98,8 @@ The Generic default ships at
 [`driver/skills/prelim-search/risk-framework.md`](../driver/skills/prelim-search/risk-framework.md)
 with bands Very High · High · Moderate · Manageable.
 
-**Replace it with your firm's own.** Write your rubric as prose, add a manifest naming your bands,
-and point a customer profile at it with `frameworkPath`. Validators, the renderer, the archive index
+**Replace it with your own.** Write your rubric as prose, add a manifest naming your bands,
+and point a company profile at it with `frameworkPath`. Validators, the renderer, the archive index
 and the config UI all read your band vocabulary from the manifest, so your words appear everywhere
 the engine names a risk.
 
@@ -132,7 +132,7 @@ That shape is not decoration. The profile screen extracts what the bands mean fr
 bullets, and **it is all or nothing**: one band without a heading, or one heading with no bold-led
 bullet, and the box explaining your bands silently does not render at all — while the title and the
 coloured pills still do, so the page looks finished. Frameworks in this repository have shipped in
-exactly that state, which is why there is now a command that tells you before a client sees it.
+exactly that state, which is why there is now a command that tells you before a reader does.
 
 **2. Write the manifest**, beside the deck and named after it: `your-framework.md` needs
 `your-framework.manifest.json`. The path is derived, never configured, so the two cannot drift apart.
@@ -160,14 +160,14 @@ than ignored. `schema_version` is `1`. `framework_key` is lowercase letters, dig
 names a risk. A band label may contain letters, spaces, slashes and hyphens, and **no digits** — a band
 called "Level 3" invites arithmetic where judgement is wanted. `tone` is one of `severe`, `high`,
 `medium`, `low`, `minimal`, and it chooses a colour, nothing else. `entity_label` is how your deck names
-the client side in prose. If your deck is a matrix rather than a ladder, say
+the company in prose. If your deck is a matrix rather than a ladder, say
 `"structure": { "kind": "matrix" }` — the matrix itself lives in the deck prose, never here.
 
 **The manifest carries vocabulary and order only.** No threshold, no mapping table, no decision rule.
 Those belong in the deck, where they are read as reasoning rather than applied as arithmetic.
 
-**3. Put both files in your own store** and point a profile at the deck with `frameworkPath`. Client
-rubrics deliberately do not live inside a checkout of this product.
+**3. Put both files in your own store** and point a profile at the deck with `frameworkPath`. A
+company's rubric deliberately does not live inside a checkout of this product.
 
 **4. Check it before it is in force**, with the pre-flight. It opens both files exactly as a run would,
 prints what they declare, and where the deck and the manifest disagree it names the band and says what
@@ -207,7 +207,7 @@ It exits 0 when the two agree and 1 when they do not, so it can gate a deploymen
 brandowner add --dry-run` prints the same report for the framework it would set.
 
 **It also tells you which file answered.** Resolution looks in your store first and falls back to this
-repository, and the repository ships decks under names a customer may well have chosen too. A deck that
+repository, and the repository ships decks under names you may well have chosen too. A deck that
 went missing from your store is therefore replaced by ours rather than reported absent — same band
 words, different rubric, nothing raised anywhere. When that happens the report says so, above the
 verdict, and the profile screen writes a line to the log.
@@ -231,10 +231,10 @@ look exactly like right ones.** Have it read by whoever would sign the advice, b
 
 ---
 
-## 3. Client profiles
+## 3. Company profiles
 
-One JSON file per client under [`driver/profiles/`](../driver/profiles/). Two are published as working
-examples: `generic` (the Generic default) and the demo brand owner. Three further synthetic profiles —
+One JSON file per company under [`driver/profiles/`](../driver/profiles/). Two are published as working
+examples: `generic` (the Generic default) and the demo company. Three further synthetic profiles —
 gaming, functional drinks and animal health — exist in the repository for the test suite and are left
 out of the package.
 
@@ -248,8 +248,8 @@ frozen into the run's own sidecar, so editing a profile mid-run cannot change a
 |---|---|
 | `name`, `matchDomains[]` | Identity and resolution. Overlapping domains across files is a load-time error. |
 | `platforms[]` | The store domains the common-law sweep covers. The general-web cell is implicit — never list it. |
-| `defaultClasses[]`, `defaultJurisdictions[]` | What the matter assumes when a request names neither. |
-| `selfExclusionOwners[]` | The client's own and affiliate names, so their own rights are not reported as conflicts against them. |
+| `defaultClasses[]`, `defaultJurisdictions[]` | What a clearance assumes when a request names neither. |
+| `selfExclusionOwners[]` | The company's own and affiliate names, so its own rights are not reported as conflicts against it. |
 | `industry` | Sector context that sharpens which adjacencies matter. Context, never a rule that decides. |
 | `riskAppetite` | A prose posture that flavours emphasis and recommended follow-up. |
 | `marketplaceDensity` | `sparse` (default) or `dense` — the per-profile sweep budget. Dense fits long retail listings; gaming stores stay sparse. |
@@ -287,6 +287,6 @@ in [`PORTAL.md`](PORTAL.md).
 | Profile internals and the onboarding runbook | [`architecture/05-customer-profiles.md`](architecture/05-customer-profiles.md) |
 | What each product searches | [`../driver/products.mjs`](../driver/products.mjs) — the declaration the engine reads |
 
-**Client profiles and frameworks are not application config.** Keep them in your own private store
+**Company profiles and frameworks are not application config.** Keep them in your own private store
 and point the engine at it with `CLEAROTRON_CUSTOMERS_DIR` — the bundled profiles are demo data, and a
-real client's rubric does not belong in a checkout of this repo.
+real company's rubric does not belong in a checkout of this repo.

package/docs/writing-standard.md

@@ -1,6 +1,6 @@
 # Writing standard
 
-Every surface a customer reads: report HTML, portal screens, README, docs. Two parts.
+Every surface a user reads: report HTML, portal screens, README, docs. Two parts.
 
 ## Part one: how to write
 
@@ -37,7 +37,7 @@ Say what the search did and what happens next. Never define the product by negat
 - Before: "What it is not. A clearance search. We drew no register conclusions and give no filing advice."
 - After: "A name that passes here goes on to clearance."
 
-## No engineering word in anything a client reads
+## No engineering word in anything a user reads
 
 Error codes, connector names, routing tables and internal identifiers are not the reader's vocabulary.
 State the limit and its consequence.
@@ -71,7 +71,7 @@ answers questions about any of them. The page carries the finding.
 
 ## A fault is fixed, or shown to the person who can act on it
 
-A customer cannot repair a missing coverage record. Narrating the failure to them turns our defect into
+A reader cannot repair a missing coverage record. Narrating the failure to them turns our defect into
 their problem.
 
 - Before: "No coverage record was produced for this run. This section normally lists what each search

package/driver/CHANGELOG.md

@@ -1,5 +1,41 @@
 # clearotron-driver
 
+## 0.3.2-beta.4
+
+### Patch Changes
+
+- 3f4367e: Fixed: A multi-country search no longer refuses to start on a form that is already showing the territories it will search. When you have not chosen territories yourself, the form shows your company's own and the search uses those.
+  
+  Fixed: A new clearance form now opens with one line saying what to do. It no longer shows two warning panels about work you have not started.
+- 3f4367e: Fixed: On a phone, the list of clearances can now be scrolled sideways to read its columns. Before, the risk word was printed on top of the date and names broke in the middle of a word.
+
+## 0.3.2-beta.3
+
+### Patch Changes
+
+- cc56786: New: an installation can name its administrator contact, a mail or web address, and Preferences links "Clearotron administrator" to it.
+  
+  New: Preferences carries the top bar's blur button, and the blur now stays as you left it in this browser, reloads included.
+  
+  New: Global config is now Installation settings, with one sign-in row, the engine's own web search under Engine, and providers grouped by category.
+  
+  New: a provider needing action says what it needs in a few words and links its setup guide, instead of naming settings and files.
+  
+  New: About lists its facts in one card, and its source link reads as the repository's name, with the build just above.
+  
+  New: the sign-in page leads with one line, "This Clearotron signs in one person: you.", and keeps the reset and sign-on steps under Administrator help.
+- cc56786: New: a report's header labels both of its dates, searched and issued, with Ask AI and Export beside them as two buttons.
+  
+  New: Ask AI on a report offers four questions, and opens Claude with the one you pick typed in, ready for you to send.
+  
+  New: Use your AI is now Connect your AI, and shows whether your assistant is connected, folding the setup steps away once it is.
+  
+  New: after Set it up on a report's Ask AI, Connect your AI offers a button back to that report once your assistant connects.
+  
+  Fixed: Claude's steps no longer tell you to ignore an authentication warning, and copy the address and the key with separate buttons.
+  
+  New: where your installation offers another way to connect, Connect your AI keeps those steps in a closed fold under the sign-in steps.
+
 ## 0.3.2-beta.2
 
 ### Patch Changes

package/driver/package.json

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

package/driver/portal-service.mjs

@@ -142,7 +142,7 @@ import { orderedQueueFiles, reorderQueue } from "./queue-order.mjs";   // the SA
 import { drainingState } from "./worker-heartbeat.mjs";   // / — is anything draining this install
 import { batchMarkName } from "./mark-name.mjs";
 import { DEFAULT_CLIENT_DAILY_RUNS, accountUsage } from "./usage-ledger.mjs";
-import { productIdentity } from "../shared/product-identity.mjs";   // AGPL §13 — one answer, three surfaces
+import { productIdentity, SOURCE_REPO } from "../shared/product-identity.mjs";   // AGPL §13 — one answer, three surfaces
 import { engineCommit } from "./engine-build.mjs";                  // — the SAME stamp pool meta records
 // — siblings, on their own line: the guard pins the line above and its subject is the JOIN
 // (this endpoint and pool meta stamp the same function), not the import list. Kept separate so that
@@ -155,7 +155,7 @@ import { readReport, reportsOf, resolveReportFile, batchSummaryOf } from "./port
 import { readArchivedSet, updateArchived } from "./publish/archive-tags.mjs";
 import { readAcks, setAck, withAcks, ACKNOWLEDGEABLE } from "./portal-acks.mjs";
 import { MAX_BRIEF, makeReadBudget } from "./compose-read.mjs";
-import { BRAND, ORGANISATION_NAME, PALETTE, FONT_LINK, FAVICON_LINK, bracketMark, DOOR_ROOT, DOOR_ROOT_DARK, DOOR_THEME_INIT } from "../shared/brand.mjs";
+import { BRAND, ORGANISATION_NAME, ADMINISTRATOR_CONTACT, PALETTE, FONT_LINK, FAVICON_LINK, bracketMark, DOOR_ROOT, DOOR_ROOT_DARK, DOOR_THEME_INIT } from "../shared/brand.mjs";
 import { envFrom, pinEnv } from "../shared/env-aliases.mjs";   // — a refusal names the name in force
 import { accessAudience, audienceLabel } from "../shared/access-audience.mjs";   // — F54; jose-free on purpose
 import { resolveNumericSetting } from "./numeric-setting.mjs";   // — the same table the engine enforces, without the throw a rendering surface must not take
@@ -1590,6 +1590,9 @@ export function makePortalService({
         return { status: 200, json: { email: principal.email, ...principalView(principal, grantsHere, accountNames),
           accounts: principal.accounts, accountNames, accountFacts,
           concurrentRuns: concurrentRunsCap(), brand: ORGANISATION_NAME, engineMode: meEngineMode,
+          // WHERE A PERSON ASKS FOR A CHANGE TO THEIR SIGN-IN, beside the brand and read where it is read:
+          // an href Preferences links "Clearotron administrator" to, or null, and then the words are plain.
+          administratorContact: ADMINISTRATOR_CONTACT,
           // WHETHER THE PROGRAM IS ON THIS BOX WHILE THE ENGINE CANNOT SEE IT — true, false, or null
           // for "this could not be checked". The screen above renders one of three remedies from it,
           // and they are different remedies: install the CLI, restart the service that cannot see it,
@@ -2494,6 +2497,9 @@ async function connectorDoorKind(url) {
           // surface serves a loopback address to anybody, and the door's running-or-not stopped being
           // a question the moment it auto-started with the product.
           publicAddress: url,
+          // THE KEY DOOR'S OWN HOST, when one is deployed. Beside a sign-in door its steps ride along for
+          // the page to fold away; they are never resolved against `url`, which refuses a key.
+          keyAddress: keyUrl,
           operator: principal.email ?? null,
           // WHAT THE DOOR ANSWERS, read from the door rather than assumed by the row. The steps used to
           // be fixed: Claude's said to paste a key and set authentication to None, which is right for a
@@ -3848,6 +3854,17 @@ const escHtml = (t) => String(t).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<"
 //
 // The dark ground moved with that change: the block this page used to carry had guessed #17150f/#ece5d8,
 // and brand pack §01 fixes dark at #0f0e0c near-black + #f0e8d8 parchment. The pack wins.
+// ── THE PLAIN LINE LEADS; THE ADMINISTRATOR'S TWO LINES STEP BACK INTO A FOLD ────────────────────────
+//
+// A person arriving here needs the field, the button, and one fact: this install signs in one person.
+// The reset command and the way to add people are an administrator's business, so they sit in a closed
+// "Administrator help" fold, word for word as they were, with the same link People gives to putting a
+// login system in front. A `<details>` needs no script, which this door must render without.
+//
+// The reset command can be long — a pinned version, a base directory — so it wraps inside the card at the
+// card's own width rather than pushing past its edge.
+export const LOGIN_IN_FRONT_DOC = `${SOURCE_REPO}/blob/main/docs/PORTAL.md#putting-your-own-login-provider-in-front`;
+
 export function loginPage({ email, error = null, signedIn = false, discarded = false, resetCommand = null }) {
   const reset = resetCommand || `${bareInvocation("passphrase")} --reset`;
   const title = signedIn ? "Signed in" : "Sign in";
@@ -3883,7 +3900,16 @@ ${DOOR_THEME_INIT}
          border:1px solid var(--err-line); color:var(--err-ink); font-size:14px; }
   .hint { margin-top:18px; font-size:13px; }
   code { font-family:var(--mono); font-size:12.5px; background:var(--code-bg);
-         padding:1px 5px; border-radius:4px; }
+         padding:1px 5px; border-radius:4px; overflow-wrap:anywhere; }
+  .lead { margin:18px 0 0; padding-top:14px; border-top:1px solid var(--line); font-size:13.5px; color:var(--ink); }
+  .lead b { font-weight:600; }
+  .fold { margin-top:10px; }
+  .fold > summary { display:inline-flex; align-items:center; gap:6px; list-style:none; cursor:pointer;
+                    font-size:13px; color:var(--link); }
+  .fold > summary::-webkit-details-marker { display:none; }
+  .fold .chev { flex:none; color:var(--muted); }
+  .fold[open] > summary .chev { transform:rotate(90deg); }
+  .fold .hint { margin:14px 0 0; }
   ${DOOR_ROOT_DARK}
 </style></head><body><div class="card">
 ${lockup}
@@ -3900,8 +3926,12 @@ ${error ? `<p class="err">${escHtml(error)}</p>` : ""}
   <input id="passphrase" name="passphrase" type="password" autocomplete="new-password" autofocus>
   <button type="submit">Sign in</button>
 </form>
+<p class="lead"><b>This ${escHtml(BRAND.name)} signs in one person: you.</b></p>
+<details class="fold"><summary><span>Administrator help</span><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m9 18 6-6-6-6"/></svg></summary>
 <p class="hint">Lost the passphrase? Run <code>${escHtml(reset)}</code> on the machine
-running this portal. It mints a new one and prints it once.</p>`}
+running this portal. It mints a new one and prints it once.</p>
+<p class="hint">To add people, put it behind a login system such as your company single sign-on. <a href="${escHtml(LOGIN_IN_FRONT_DOC)}" target="_blank" rel="noreferrer">How to set that up</a></p>
+</details>`}
 </div></body></html>`;
 }
 // THE FIELD DOES NOT INVITE THE BROWSER'S SAVED PASSWORDS. Every local install and demo answers on