clearotron 0.3.2-beta.1 → 0.3.2-beta.3

package/docs/architecture/04-configuration-reference.md

@@ -21,8 +21,8 @@ Configuration lives in three layers, resolved in this order:
 2. **The stage table** → `stages.mjs` — the single source of truth for what each pipeline stage
    runs: model tier, reasoning effort, timeouts, skills, output file, validator, message. Per-stage
    behaviour changes happen here, nowhere else.
-3. **Customer profiles** → `profiles/` — per-client knowledge and delivery configuration, frozen
-   per run. Documented in [05 — Customer profiles](05-customer-profiles.md).
+3. **Company profiles** → `profiles/` — per-company knowledge and delivery configuration, frozen
+   per run. Documented in [05 — Company profiles](05-customer-profiles.md).
 
 **Resolution semantics matter.** Every value on the `config` object is a **getter**, read at access
 time, so all of them honour a mid-process env flip — the file's own NOTE beside `config` says why:
@@ -93,8 +93,8 @@ does after the stage's full retry ladder fails ([03 §5](03-run-lifecycle.md#5--
 Notes that keep maintainers out of trouble (all verified against code):
 
 - **`skillReads` on a stage entry is declarative metadata only.** The live skill reads are the
-  `reads([...])` call inside each stage's `message()`, which resolves per-customer framework and
-  worked-examples files via the profile. Do not "reconcile" the two — that breaks per-customer
+  `reads([...])` call inside each stage's `message()`, which resolves per-company framework and
+  worked-examples files via the profile. Do not "reconcile" the two — that breaks per-company
   framework selection (guarded by `test/profiles.test.mjs`).
 - **Stage messages embed verbatim machine contracts** (`ESCALATE:` lines, `- ord:` stamps, closed
   enums, band `state` values). Code parses these strings; rewording a message can break the parser.
@@ -193,13 +193,13 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_SKILLS_STORE_STRICT` | unset (warn) | Hard mode for the run door's doctrine-store check (`driver/skills-store-provenance.mjs`). The door classifies the store `CLEAROTRON_INSTRUCTIONS_DIR` names into the publication gate's three outcomes — **pass**, **fail** (uncommitted changes under the served path, or a HEAD not contained in the main line), **blocked** (could not be determined: git absent, an unreadable ancestor, no main-line ref, or a store no commit tracks). A store affirmatively outside any checkout passes: the walk to the filesystem root must complete with every step readable, so "no git evidence" can never be inferred from a directory this process cannot see. Unset, a non-pass prints one `[preflight]` line to stderr and stamps a `skills-store` event into the run's `_driver/run.jsonl`, and the run proceeds. Set (`1`; `0`/`off`/`false`/`no`/empty do not arm it), any non-pass **refuses the run before any spend** — `blocked` included, because a store whose state nobody can name is not a store anybody can reproduce. |
 | `CLEAROTRON_SKILLS_STORE_MAIN_BRANCH` | `main` | Which branch name the check above treats as the main line. A deployment whose config store is on `master` sets this; otherwise that store has no main-line ref to be measured against and every run reports `blocked`. Only the branch name — the check prefers `origin/<name>` and falls back to the local ref. |
 | `CLEAROTRON_MIN_FREE_DISK_MB` | `500` | Free space the run door requires on the filesystem holding `CLEAROTRON_WORK_DIR`, in MB. Below it a run is **refused** before anything is written — a disk that fills mid-run surfaces as a *missing artifact* at some later stage, which is indistinguishable from an engine or provider fault. Not a sizing estimate: one real delivered run measured 5.85 MB, so 500 MB is the line below which the filesystem is in trouble for reasons of its own.`0` disables the check; a non-numeric value **throws** rather than silently disabling it. A disk that cannot be measured is reported and the run proceeds — never read as room. |
-| `CLEAROTRON_REPORTS_DIR` | **none — set it** | Publish pool (web-served). **No default since: unset refuses and names the variable.** It read`/srv/trademark-archive` — a deployed server's real client archive — so a forgotten export published into somebody else's matter, and two entry points already carried hand-written defences against exactly that (`bin/onboard.mjs`, `bin/example.mjs`). Same shape as `CLEAROTRON_DATABASE` and `scripts/purge-runs.mjs`: guessing wrong is expensive, so it does not guess. Read-only surfaces (flag snapshot, status page, MCP options) degrade to "no pool" instead of throwing; anything that writes refuses. `driver/production-pool-guard.mjs` still names `/srv/trademark-archive` on purpose — that constant is a fact about where the archive is, not a default. |
+| `CLEAROTRON_REPORTS_DIR` | **none — set it** | Publish pool (web-served). **No default since: unset refuses and names the variable.** It read`/srv/trademark-archive` — a deployed server's real archive — so a forgotten export published into somebody else's clearances, and two entry points already carried hand-written defences against exactly that (`bin/onboard.mjs`, `bin/example.mjs`). Same shape as `CLEAROTRON_DATABASE` and `scripts/purge-runs.mjs`: guessing wrong is expensive, so it does not guess. Read-only surfaces (flag snapshot, status page, MCP options) degrade to "no pool" instead of throwing; anything that writes refuses. `driver/production-pool-guard.mjs` still names `/srv/trademark-archive` on purpose — that constant is a fact about where the archive is, not a default. |
 | `CLEAROTRON_REPORTS_URL` | **none — set it** | Pool base URL used in notification links. No placeholder default: unset ⇒ the link is omitted and the runner logs `deployment config MISSING` at activation. It does not gate the queue (a missing hostname costs a link, not the deliverable), so treat that log line as the alarm. |
 | `CLEAROTRON_ACCESS_DOMAIN` | unset (note omitted) | Identity domain named in the delivery email's access note ("sign in with a `<domain>` account"). Unset ⇒ the note is omitted rather than naming the wrong domain. |
 | `CLEAROTRON_RUN_LOCK_DIR` | `<workspaceRoot>/prelim-run-locks` | Run-slot lock dir (turn locks under `…/turns`). |
 | `CLEAROTRON_OUTBOX_DIR` | `<workspaceRoot>/prelim-outbox` | Delivery outbox (`<runId>.pending` wake markers). |
 | `CLEAROTRON_OAUTH_BRIDGE` | module-relative `providers/oauth-mcp-bridge/bridge.mjs` | Case-law MCP bridge script. (Portable since the module-relative default; set explicitly only for a bridge outside the repo tree.) |
-| `CLEAROTRON_REGISTER_CALL_LOG` | `~/trademark/telemetry/register-calls.jsonl`, or the existing file wherever it already is | Billing-grade provider-call ledger, shared by whichever ONE register provider is wired — not a vendor artifact. Every read site derives the default from`homedir()` at call time (2026-07-19: two sites had hardcoded a literal account home, splitting the ledger under any other service account — guarded by `test/deployment-hostnames.test.mjs`). |
+| `CLEAROTRON_REGISTER_CALL_LOG` | `~/trademark/telemetry/register-calls.jsonl`, or the existing file wherever it already is | Billing-grade provider-call ledger, shared by whichever ONE register provider is wired — not a vendor artifact. Every read site derives the default from`homedir()` at call time (2026-07-19: two sites had hardcoded a literal home directory, splitting the ledger under any other service account — guarded by `test/deployment-hostnames.test.mjs`). |
 | `CLEAROTRON_REGISTER_RECORD_LOG` | **runtime-injected per run**: `<runDir>/_driver/register-record-bodies.jsonl` | Citation-fidelity log: the BODY of every fetched official record. ** moved it INTO the run** — created with the run, unioned into the run's`_records/`, archived and purged with it. There is no retention setting and no cleanup job, because it no longer grows on the box: held globally it reached 432 MB in 61 days on production and needed a rotation timer on every install. **Do not set this by hand** — a fixed value pins every run's bodies to one file and restores the problem. A box upgraded across still holds its old global file; nothing writes or reads it, the driver names it once per process on stderr, and archiving it is one`mv`. An empty log cannot read as verified: the run's successful `record_fetch` rows in the (still global) call ledger are compared against the assembled record set, and a gap is reported as a failure. |
 | `CORSEARCH_CALL_LOG` / `CORSEARCH_RECORD_LOG` | — | **Deprecated, honoured for one release.** These are the names these two variables carried before the rename. Unset on every deployed box (all three ran the homedir default), so what actually protects an upgrade is the filename fallback: a`corsearch-calls.jsonl` / `corsearch-records.jsonl` already on disk keeps being read where it sits. Resolution order is in `providers/_shared/ledger-path.mjs`. |
 | `CLEAROTRON_BAND_RUN_DIR` | set per dispatch | The run dir the band MCP server writes into, injected per stage — unset means the server has no run to write to and says so rather than guessing one. |
@@ -219,7 +219,7 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_RUN_LOCK_POLL_MS` | 15000 | Run-slot acquire poll cadence. |
 | `CLEAROTRON_ADMISSION_BUDGET_MS` | 7200000 (2 h) | Runner stops claiming new jobs after this per activation; leftovers re-trigger a fresh activation. |
 | `CLEAROTRON_QUEUE_SCAN_MS` | 10000 (min 1000) | Mid-drain re-scan for newly arrived jobs. |
-| `CLEAROTRON_WHATIF_MAX_CONCURRENT` | 1 (min 1) | How many client what-ifs the runner drains at once. Deliberately NOT a run-slot: an experiment that took one from `CLEAROTRON_MAX_CONCURRENT_RUNS` could block an admitted paid clearance rather than merely share the box with it. This is a concurrency bound and not a spend control — the owner ruled spend controls out when he opened what-if to clients (2026-08-27), and nothing here refuses a client's next experiment. |
+| `CLEAROTRON_WHATIF_MAX_CONCURRENT` | 1 (min 1) | How many queued what-ifs the runner drains at once. Deliberately NOT a run-slot: an experiment that took one from `CLEAROTRON_MAX_CONCURRENT_RUNS` could block an admitted paid clearance rather than merely share the box with it. This is a concurrency bound and not a spend control — the owner ruled spend controls out when he opened what-if to each company's people (2026-08-27), and nothing here refuses the next experiment. |
 | `CLEAROTRON_STOP_GRACE_MS` | 60000 | Grace after first SIGTERM before exit(1). |
 | `CLEAROTRON_MAX_CLAIM_AGE_MS` | 172800000 (48 h; 0 disables) | Hard ceiling on a claim's age (from the `.pid` sidecar mtime) — beyond it, re-claim regardless of liveness. |
 | `CLEAROTRON_KNOCKOUT_VARIANT_CAP` | unset (⇒ the lane's own cap) | Ceiling on variants a knockout screens per name. Set only to bound an unusually wide batch; absent means the lane decides. |
@@ -284,8 +284,9 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `DEMO_PORT` | `18900` | Port `npx clearotron demo` serves the replayed report on. `--port` overrides it. |
 | `CLEAROTRON_DEMO` | unset | `1` puts this install in the DEMO posture. **Ordering is real**: the four products are listed and orderable, the form, the plan and the confirmation are the product's own, and the confirmation resolves to a finished report that already exists rather than dispatching — no engine turn, no register call, no queue entry, no run directory (ruling 2026-08-31, superseding the greyed-control ruling of the same day). A product the demo carries no finished report for refuses and names which one. It also re-aims two boot warnings written for an operator of a real deployment at the visitor who is not one, from one place (`driver/demo-posture.mjs`). **Set by `npx clearotron demo`, not by an operator** — it is passed explicitly to the two processes that have a reason to know (the portal and the MCP door; the worker is not told, because a demo never queues anything for it to drain), and those run with `CLEAROTRON_NO_ENV_FILE=1`, so a stray `.env` can neither put a live install into demo mode nor take a demo out of one. Anything but the literal `1` is not a demo. Replaces `PORTAL_DEMO`, which named only one of the processes that has to know. |
 | `CLEAROTRON_TEST_FIXTURE_PROFILES` | unset | `1` makes the profile loader return the three suite fixtures, which are refused from every roster otherwise. Set by `scripts/test-run.mjs`, never by an operator; an explicit `includeTestFixtures` argument beats it. Effect class `harness`; the full contract is its row in `.env.example`. |
-| `CLEAROTRON_DEMO_PROFILES` | unset | `1` makes the profile loader return the bundled demo account, which a fresh install does not resolve (ruling 2026-09-08). Set by `clearotron demo`, `start --demo` and the suite runner, never by an operator. The gate is on the bundled layer, so a deployment's own configured store keeps its `demoData` accounts either way. Effect class `harness`; the full contract is its row in `.env.example`. |
+| `CLEAROTRON_DEMO_PROFILES` | unset | `1` makes the profile loader return the bundled demo company, which a fresh install does not resolve (ruling 2026-09-08). Set by `clearotron demo`, `start --demo` and the suite runner, never by an operator. The gate is on the bundled layer, so a deployment's own configured store keeps its `demoData` companies either way. Effect class `harness`; the full contract is its row in `.env.example`. |
 | `CLEAROTRON_ORGANISATION_NAME` | unset | Your organisation's name, written quoted by `npx clearotron install`, which asks for it and not for a sign-in address. The first `clearotron start` files it as the first organisation in the grants file (`CLEAROTRON_ACCESS_FILE`) when that file holds none; from then on the grants file holds the name and renaming is an edit there. The portal also reads it, to name the organisation on its top bar and on its sign-in refusal page. Unset ⇒ no organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a demo never reads it. Effect class `deployment`; the full contract is its row in `.env.example`. |
+| `CLEAROTRON_ADMINISTRATOR_CONTACT` | unset | Who a signed-in person contacts to change the address, the permissions or the companies on their sign-in: a mail address (with or without `mailto:`) or an http(s) address. The portal reads it where it reads the organisation name and sends it on the same `/me` answer; Preferences then links the words "Clearotron administrator" to it. Unset, or any value that is neither a mail nor a web address, ⇒ the words are plain text. Effect class `deployment`; the full contract is its row in `.env.example`. |
 | `PORTAL_LOCAL_CREDENTIAL` | `~/.cordillera/portal-local-credential.json` | Where local sign-in keeps its passphrase DIGEST. `clearotron start` points it inside the install's own base directory for a new install, so it mints its own passphrase instead of adopting a digest another install left; an install that has been signing in with the shared file keeps it. `npx clearotron demo` always points it inside the demo's own base directory and mints a new passphrase there on every start, so a demo never inherits a digest minted for another address, and removing the demo stays one `rm -rf`. |
 | `PORTAL_LOCAL_PASSPHRASE` | unset | **NEVER set this in a file.** An internal one-shot handoff, not an operator control: on a first FOREGROUND start the supervisor mints the passphrase and hands it to the portal it spawns *at the spawn call*, so the closing summary can print the value beside the address rather than sending a first-time reader back into eleven startup log lines for the one value in this product that cannot be read back. It is deliberately absent from the composed child environments, because that composition is what `--background` writes into the units' env file — a passphrase there would be a permanent plaintext copy on disk and the product's own sentence, "it is stored only as a digest", would stop being true. Setting it in any env file recreates exactly that. Lost passphrase: `clearotron passphrase --reset`. |
 | `PORTAL_URL` | `http://127.0.0.1:18802`, or built from `PORTAL_SERVICE_HOST`/`PORTAL_SERVICE_PORT` | Where the deploy tick's live-surface check expects to reach the portal. |
@@ -296,7 +297,8 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `CLEAROTRON_UPDATER_STAMP` | `_updater-identity.json` beside the update script, in the directory the updater runs from | The full path of the file in which the updater that deploys this box records which copy of itself ran. The updater writes it and deploy health reads it under this one name, so a box that moves the stamp sets it once for both. On a box with no updater unit, setting it says an updater exists elsewhere and is to be judged. Effect class `deployment`. |
 | `CLEAROTRON_CUT_REF` | `HEAD` | Which ref the cut decision reads the version from. **Read only by the release workflow, never set on a deployment.** The jobs that ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref and `HEAD` there is that ref rather than the branch they are deciding about. A job that asks the wrong subject gets a confident wrong answer. |
 | `CLEAROTRON_RELEASE_WAIT_MS` | 25 minutes | How long a requested cut waits for the version pull request to merge itself before giving up. **Read only by the release workflow.** A rehearsal sets it to `0` so the wiring is exercised without holding a runner. Giving up is a quiet success by design — the scheduled run underneath catches a cut whose wait expired — so this budget failing shows up as a slow job rather than a red one. |
-| `CLEAROTRON_AGENT_MCP_URL` | unset (⇒ `null`) | The API-key MCP door advertised to a signed-in client. Null until that door is deployed, and the UI keeps its honest empty state rather than inventing a URL. |
+| `ACTIONS_APPROVE_TOKEN` | unset | A GitHub token with Actions read and write, used to approve the version pull request's parked CI run so a cut does not wait for a person. **Read only by the release workflow, never set on a deployment.** The built-in token cannot approve a run — GitHub blocks self-approval — so this is a second, separate credential. Unset is the ordinary case and not an error: the script names the absent token and exits successfully, and the version run waits for a person as it did before. Actions write is broader than approval alone — it also dispatches workflows, cancels any run in the repository and deletes run logs. |
+| `CLEAROTRON_AGENT_MCP_URL` | unset (⇒ `null`) | The API-key MCP door advertised to a signed-in person. Null until that door is deployed, and the UI keeps its honest empty state rather than inventing a URL. |
 | `CLEAROTRON_AGENTS` | derived | Comma-separated agent ids for `scripts/purge-runs.mjs` to sweep. |
 | `CLEAROTRON_E2E_DIR` | **none — the script refuses without it** | The config repo's `e2e/` directory. There is one suite and it is not in this repo (ruling 2026-08-07), so the comparison script names the variable rather than defaulting anywhere. |
 | `CLEAROTRON_E2E_EXPECT_DEMO_ROSTER` | unset | `1` makes the live-surface check REQUIRE the bundled demo roster. For a box that is meant to ship the demos; off elsewhere, so a real deployment is not failed for lacking them. |
@@ -323,14 +325,14 @@ cannot be read as one list.
 | `PERPLEXITY_API_KEY` | Marketplace grid research server. |
 | `EUIPO_CLIENT_ID` / `EUIPO_CLIENT_SECRET` / `EUIPO_ENVIRONMENT` | EUIPO OAuth2 client-credentials; environment defaults to **sandbox** — production requires an explicit set. |
 | `CLEAROTRON_MCP_URL` | Staff "Ask your AI" connector base, baked into the report at render — there is one report, and `portal-report.mjs` strips the block for non-staff readers at serve time. Fails closed → link omitted when unset. |
-| `CLEAROTRON_CLIENT_MCP_URL` | Client "Ask your AI" connector base, served LIVE by the portal's `/portal/api/mcp-access` (the Use-your-AI screen) — set it on the portal unit, or the screen shows its (correct) empty state. The render no longer reads it: the baked block is the staff connector above. Fails closed → `{url:null}` when unset. **Never pin a placeholder value:** the fail-closed branch keys on the var being EMPTY, so a placeholder host defeats the guard and hands out a dead connector address. |
-| `CLIENT_MCP_ACCOUNT_ACCESS` | `1` admits the signed-in CLIENT principal (kind `account`) on the client MCP surface: no token, scoped to the accounts the CF-verified email is granted. Off by default. Set WITHOUT `CLEAROTRON_ACCESS_FILE` ⇒ fatal start (`accountsForEmail` answers `"*"` with no guest list, and an unscoped wildcard must never be admitted). See `docs/CLIENT-MCP.md` — enabling this for an account with no `runCaps.dailyRuns` lets it start paid searches all day. |
+| `CLEAROTRON_CLIENT_MCP_URL` | The client connector's "Ask your AI" base address, served LIVE by the portal's `/portal/api/mcp-access` (the Use-your-AI screen) — set it on the portal unit, or the screen shows its (correct) empty state. The render no longer reads it: the baked block is the staff connector above. Fails closed → `{url:null}` when unset. **Never pin a placeholder value:** the fail-closed branch keys on the var being EMPTY, so a placeholder host defeats the guard and hands out a dead connector address. |
+| `CLIENT_MCP_ACCOUNT_ACCESS` | `1` admits the signed-in principal from outside your staff (kind `account`) on the client MCP surface: no token, scoped to the companies the CF-verified email is granted. Off by default. Set WITHOUT `CLEAROTRON_ACCESS_FILE` ⇒ fatal start (`accountsForEmail` answers `"*"` with no guest list, and an unscoped wildcard must never be admitted). See `docs/CLIENT-MCP.md` — enabling this for a company with no `runCaps.dailyRuns` lets it start paid searches all day. |
 
 ### Scrub guard
 
 | Var | Default | Meaning |
 |---|---|---|
-| `CLEAROTRON_IDENTIFIER_BLOCKLIST` | unset (⇒ sentinels) | Path to `identifier-blocklist.json` in the customer-config store: every customer and mark this repo has carried, paired with the demo twin that replaced it. Read by the client-identifier guard and the publication scan, never on a run path. **Unset is a supported mode**, not a degraded one — the guard runs on synthetic sentinels built into it, which exercise every branch of the matcher and identify nobody; that is how the public repository runs it. Set but unreadable, malformed, or below the size floor ⇒ **throws** (a truncated table reads as a smaller blocklist, and a smaller blocklist reads as a cleaner repo). The table is kept out of the product repo because the list of names *is* the thing the guard protects. |
+| `CLEAROTRON_IDENTIFIER_BLOCKLIST` | unset (⇒ sentinels) | Path to `identifier-blocklist.json` in the config store: every real company and mark this repo has carried, paired with the demo twin that replaced it. Read by the identifier guard and the publication scan, never on a run path. **Unset is a supported mode**, not a degraded one — the guard runs on synthetic sentinels built into it, which exercise every branch of the matcher and identify nobody; that is how the public repository runs it. Set but unreadable, malformed, or below the size floor ⇒ **throws** (a truncated table reads as a smaller blocklist, and a smaller blocklist reads as a cleaner repo). The table is kept out of the product repo because the list of names *is* the thing the guard protects. |
 
 ### A/B, telemetry, debug
 
@@ -341,7 +343,7 @@ cannot be read as one list.
 | `CLEAROTRON_STAGE_THINKING` | unset (⇒ each stage's declared tier) | Per-stage thinking-tier override, `<stage>=<tier>[,…]` (e.g. `register-digest=high`) — the A/B instrument, so a suite arm needs no code fork or redeploy between runs. Thinking only: models are deliberately not overridable here, so one arm can never move two variables. **The env override is a dev/test instrument**; a permanent change edits the tier in `stages.mjs` and ships. Unknown stage or tier **throws** — `effortFor()` falls back to `medium`, so a typo would otherwise run a stage at a tier nobody chose and every number measured against it would be wrong. Read per call, so an arm can flip mid-process. |
 | `CLEAROTRON_AZURE_MODEL` | `azure-openai/gpt-5.4` | Target of the `azure` alias — a legacy catalogue entry no engine can run (see model tiers above). |
 | `CLEAROTRON_DUMP_JSON` | unset | Dump each attempt's raw engine envelope to `_driver/<stage>.attempt<N>.rawjson.json`. Opt-in: any value except `0`/`off`/`false`/`no`/empty arms it. |
-| `CLEAROTRON_DISPATCH_RECORD` | **on** | Write the verbatim message of every stage dispatch to `_driver/<stage>.attempt<N>[.repair<M>].dispatch.txt`, with `{file, sha, bytes, chars, kind}` on the attempt row. **Default ON** — `0`/`off`/`false`/`no` disarms it. Unlike `CLEAROTRON_DUMP_JSON` beside it, this is opt-OUT: the question it answers ("was the model given this?") is asked *after* the run that raised it, so a flag someone had to remember would be off on exactly the run that needed it. The files carry client identity verbatim and are deliberately not in the artifact table. |
+| `CLEAROTRON_DISPATCH_RECORD` | **on** | Write the verbatim message of every stage dispatch to `_driver/<stage>.attempt<N>[.repair<M>].dispatch.txt`, with `{file, sha, bytes, chars, kind}` on the attempt row. **Default ON** — `0`/`off`/`false`/`no` disarms it. Unlike `CLEAROTRON_DUMP_JSON` beside it, this is opt-OUT: the question it answers ("was the model given this?") is asked *after* the run that raised it, so a flag someone had to remember would be off on exactly the run that needed it. The files carry the company's identity verbatim and are deliberately not in the artifact table. |
 | `CLEAROTRON_GATHER_SESSION_KEY` / `CLEAROTRON_GATHER_AGENT` / `CLEAROTRON_GATHER_SESSION_ID` | set per stage | Telemetry attribution into the provider-call ledger (set by the gather config; not operator-set). |
 | `CLEAROTRON_RECORD_AXIS` | set per dispatch (unset ⇒ the stage is not fanned out) | Binds one fan-out turn of a recording stage to the single member it may write. `stageOnce` suffixes a fan-out stage's label with its axis, the gather config resolves `<stage>:<axis>` back to the base stage's tool group, and this carries the axis to the recording server. A call whose payload names a different member than the turn is bound to is REFUSED, so a seat cannot write into a sibling's file — without the binding every turn of the fan-out would record over member one. Set by the driver; not operator-set. |
 | `PORTAL_READ_MODEL` | `claude-sonnet-5` | The model the portal's own compose-read turn uses. Distinct from the pipeline's tiers: this is a portal surface, not a stage. |

package/docs/architecture/05-config-governance.md

@@ -22,16 +22,16 @@
 
 | Tier | Who changes it | Through what | Examples |
 |---|---|---|---|
-| **T1 — Client** | The client (self-service) | Agent conversation → job spec; client portal | mark, classes, deadline, own profile fields, flags |
-| **T2 — Staff/ops UI** | Firm staff | the portal's brand screens, profile-service | customer profiles, project overlays, saved searches, run curation |
+| **T1 — Company** | A company's own people (self-service) | Agent conversation → job spec; the portal | mark, classes, deadline, own profile fields, flags |
+| **T2 — Staff/ops UI** | The operator's staff | the portal's company settings screens, profile-service | company profiles, project overlays, saved searches, run curation |
 | **T3 — Operator env** | Ops, on the box | the EnvironmentFile + restart/next-activation | hostnames, models, caps, timeouts, feature gates |
 | **T4 — Backend-only** | Ops, deliberately | env secrets, unit files, code defaults | credentials, token secrets, data-plane paths, dev seams |
-| **T5 — Edge auth** | Ops, in the edge console | the auth proxy's own console, off-box (reference: a Cloudflare Zero-Trust tenant) | ingress routes, access apps + policies |
+| **T5 — Edge auth** | Ops, in the edge console | the auth proxy's own console, off-box (reference: Cloudflare Zero Trust) | ingress routes, access apps + policies |
 
-The UI mapping, as the `portal-ui` nav is actually structured: T2 → **`brand.profile`** ("Brand
-profile", everything specific to one brand owner) + **`brand.projects`** + **`brand.searches`**
-("Custom searches"), plus **`admin.access`** ("People & access") for who may sign in; T3 →
-**read-only** in **`admin.config`** ("Global config"): which engine is running the searches and who is
+The UI mapping, as the `portal-ui` nav is actually structured: T2 → **`brand.profile`** ("Profile",
+everything specific to one company) + **`brand.projects`** + **`brand.searches`**
+("Search templates"), plus **`admin.access`** ("People & access") for who may sign in; T3 →
+**read-only** in **`admin.config`** ("Installation settings"): which engine is running the searches and who is
 billed for them, and every provider a search depends on with a configured-or-missing state — secrets,
 paths and switch names deliberately excluded, visible to staff, changed only on the backend.
 
@@ -55,8 +55,8 @@ recorded.
 |---|---|---|---|
 | 1 | The EnvironmentFile (`%h/.env`) | secrets + T3 operator env for the generic units | ops, by hand. **Keep it dedicated to this product where possible** — sharing one env file with another stack couples rotation and backup blast-radius across products |
 | 2 | systemd user units (`driver/systemd/`, `mcp-server/remote/`) | ports, CF Access mirrors, paths. Two kinds — **generic** (defer to the EnvironmentFile; safe to sync verbatim) vs **template** (placeholders in-repo, real identity-edge values in the live copies; merge by hand after a diff — banner-marked). Copying a template over a live unit replaces working auth with placeholders that *look* configured, which is why the two kinds are distinguished at all | this repo's deploy |
-| 3 | The config store (separate git repo) | customer profiles, project overlays, frameworks/skills | profile-service + client portal git auto-commit; frameworks by git edit (deliberate) |
-| 4 | Client allowlist file (`CLIENT_ACCESS_MAP` JSON) | client per-email → customer grants | git + PR (today it lives in the integrator's repo — a candidate to move into the config store so the product owns all its config) |
+| 3 | The config store (separate git repo) | company profiles, project overlays, frameworks/skills | profile-service + portal git auto-commit; frameworks by git edit (deliberate) |
+| 4 | The allowlist file (`CLIENT_ACCESS_MAP` JSON) | per-email → company grants | git + PR (today it lives in the integrator's repo — a candidate to move into the config store so the product owns all its config) |
 | 5 | Web-server / edge routing (reverse-proxy block or tunnel ingress; this deployment: Caddy + Cloudflare) | which hostname reaches which loopback port; the pool's file-server root | ops |
 | 6 | Data roots (`CLEAROTRON_REPORTS_DIR`, shares) | published reports, quality flags | services |
 | 7 | **Edge console** (off-box; reference: Cloudflare) | ingress routes + access apps and who they admit | ops — **not recoverable from the box**; keep an exported note of apps/AUDs in the deployment's ops repo |
@@ -75,7 +75,7 @@ fills the same three roles, and the product requires none of them by name.
    `MCP_ALLOWED_EMAIL_DOMAINS` appear in unit files as **mirrors of the dashboard**, not a second
    setup. They must match the edge; rotation touches both. The CF-gated loopback services
    deliberately do NOT load the shared EnvironmentFile so one app's AUD can't shadow another's
-   (client-access/client-mcp refuse to start if client AUD == staff AUD).
+   (`client-access`/`client-mcp` refuse to start if the client AUD == the staff AUD).
 3. **Rendered links (T3, env):** `CLEAROTRON_REPORTS_URL`, `CLEAROTRON_MCP_URL`, `CLEAROTRON_CLIENT_MCP_URL`,
    `CLEAROTRON_ACCESS_DOMAIN` are neither of the above — they are what gets *printed into reports and
    emails*. Wrong values render dead links; unset values are omitted.
@@ -88,18 +88,18 @@ product doc.
 
 | Surface | Tier | Managed via | Storage | State today |
 |---|---|---|---|---|
-| **Job spec** (per matter): id, forwarder(+email/domain), markName/marks[], classes\|goods/use, ref, profileKey, projectKey, searchLevel/recipeKey, deliveryRoute, customer(+Unknown), deliverableSpec, commercialFlexibility, priorUse, dupOverride, deadline, brief | T1 | agent conversation → `start_run` MCP verb (ops token) → queue; validated by `enqueue-schema.mjs` | queue → run dir | LIVE (conversational; portal `run/plan`+`run` API exists) |
-| **Customer profile** (17 keys — identity/rating/provenance: name, matchDomains, selfExclusionOwners, frameworkPath, workedExamplesPath, allowedRecipes, jxPolicy, runCaps, demoData (`true` marks the record as demo data; a real clearance is refused at the runner's admission wall); overlayable: platforms, defaultClasses, defaultJurisdictions, marketplaceDensity, delivery, riskAppetite, industry, defaultProduct) | T2 (staff) + T1 (client edits own via portal §C) | profile-service UI (staff, `/profiles/*`); client-access UI (own profile) | config store, git auto-commit | LIVE. Merge law: project **replaces** every overlayable key except `platforms`, which **unions** (client floor never subtractable) |
-| **Project overlays** (8 overlayable keys) | T2 | profile-service UI | config store `profiles/projects/<cust>/` | LIVE. The project form deliberately withholds `defaultProduct` and both `delivery` sub-keys — for the first the sparse save path has no `""` ⇒ clear branch, so the control could only ever be turned on; for the second the engine replaces `delivery` wholesale, so a partial overlay would silently drop the customer's other sub-keys. Both are customer-level controls until the server side changes |
+| **Job spec** (per matter): id, forwarder(+email/domain), markName/marks[], classes\|goods/use, ref, profileKey, projectKey, searchLevel/recipeKey, deliveryRoute, `customer`(+Unknown), deliverableSpec, commercialFlexibility, priorUse, dupOverride, deadline, brief | T1 | agent conversation → `start_run` MCP verb (ops token) → queue; validated by `enqueue-schema.mjs` | queue → run dir | LIVE (conversational; portal `run/plan`+`run` API exists) |
+| **Company profile** (17 keys — identity/rating/provenance: name, matchDomains, selfExclusionOwners, frameworkPath, workedExamplesPath, allowedRecipes, jxPolicy, runCaps, demoData (`true` marks the record as demo data; a real clearance is refused at the runner's admission wall); overlayable: platforms, defaultClasses, defaultJurisdictions, marketplaceDensity, delivery, riskAppetite, industry, defaultProduct) | T2 (staff) + T1 (a company's people edit its own via portal §C) | profile-service UI (staff, `/profiles/*`); the portal (own profile) | config store, git auto-commit | LIVE. Merge law: project **replaces** every overlayable key except `platforms`, which **unions** (the company's floor is never subtractable) |
+| **Project overlays** (8 overlayable keys) | T2 | profile-service UI | config store `profiles/projects/<cust>/` | LIVE. The project form deliberately withholds `defaultProduct` and both `delivery` sub-keys — for the first the sparse save path has no `""` ⇒ clear branch, so the control could only ever be turned on; for the second the engine replaces `delivery` wholesale, so a partial overlay would silently drop the company's other sub-keys. Both are company-level controls until the server side changes |
 | **Frameworks / skills** (risk-framework-<key>.md + .manifest.json, worked examples, SKILL.md) | T2 (senior-lawyer content) | git edits in the config store (deliberate — the prose deck is the rating authority) | config store `skills/prelim-search/` | LIVE via git; no UI by design |
 | **Recipes / saved searches** (base level + component toggles + emailTable/defaultDeadlineDays/standingInstructions) | T2 | recipe-service UI | `<recipesDir>/<cust>/<slug>.json`, git | **DARK** — code complete, no unit deployed. A saved search is honoured wherever it resolves (the `CLEAROTRON_RECIPES_MODE` door was retired 2026-07-27) |
 | **Run curation** (archive folds, republish, index regen) | T2 | `pool-admin.mjs` CLI only | pool `archive-tags.json` | LIVE, CLI-only |
-| **Client allowlist** (`{version, grants:[{email, customer}]}`) | T2 | git + PR on the `CLIENT_ACCESS_MAP` file | see §2 row 4 | LIVE, file-only; surfaced read-only at `admin.access` |
-| **Ops tokens** (scope ops/user, verbs, accounts, TTL) | T4 | `mint-token.mjs` CLI; jti denylist file | operator-held tokens | LIVE, CLI |
+| **Allowlist** (`{version, grants:[{email, customer}]}`) | T2 | git + PR on the `CLIENT_ACCESS_MAP` file | see §2 row 4 | LIVE, file-only; surfaced read-only at `admin.access` |
+| **Ops tokens** (scope ops/user, verbs, companies, TTL) | T4 | `mint-token.mjs` CLI; jti denylist file | operator-held tokens | LIVE, CLI |
 
 ## 4b. The install surface names ()
 
-The variables a **customer or installer** ever types carry the product’s own prefix. They are listed
+The variables a **user or installer** ever types carry the product’s own prefix. They are listed
 by name in §5 below and in the upgrade table in INSTALL.md.
 `CLEAROTRON` is the internal codename of the first product this engine shipped and means nothing to a reader
 who has not read the code. Vendor credentials keep the vendor’s name (`SIGNA_API_KEY`,
@@ -152,8 +152,9 @@ structural, or dev seam); [dev] = dev/test seam, never set in prod.
 | `CLEAROTRON_MCP_URL` | fail-closed omit | Staff "Ask your AI" connector base |
 | `CLEAROTRON_CLIENT_MCP_URL` | fail-closed omit | Client connector base |
 | `CLEAROTRON_ACCESS_DOMAIN` | omit note | Identity domain in the delivery email access note |
-| `CLEAROTRON_BOX` | none — required (unset or unrecognised ⇒ the unit-inventory line fails and names this variable) | Which deployment this is (`prod` \| `test`), for `scripts/live-surface-check.mjs`'s unit inventory. Self-declared, never inferred from the account name. Without a recognised value, the half that looks for a unit declared here and not running cannot run, because a guess would report every other deployment's units missing; so the line fails instead of passing with that half unrun |
-| `CLEAROTRON_BRAND_NAME` / `CLEAROTRON_BRAND_TAGLINE` / `CLEAROTRON_BRAND_PRODUCT` | reference-tenant literals in `shared/brand.mjs` | Tenant brand seam (single-sourced) |
+| `CLEAROTRON_BOX` | none — required (unset or unrecognised ⇒ the unit-inventory line fails and names this variable) | Which deployment this is (`prod` \| `test`), for `scripts/live-surface-check.mjs`'s unit inventory. Self-declared, never inferred from the login name. Without a recognised value, the half that looks for a unit declared here and not running cannot run, because a guess would report every other deployment's units missing; so the line fails instead of passing with that half unrun |
+| `CLEAROTRON_BRAND_NAME` / `CLEAROTRON_BRAND_TAGLINE` / `CLEAROTRON_BRAND_PRODUCT` | reference-deployment literals in `shared/brand.mjs` | Installation brand seam (single-sourced) |
+| `CLEAROTRON_ADMINISTRATOR_CONTACT` | unset ⇒ plain text, no link | The administrator contact Preferences links "Clearotron administrator" to — a mail or http(s) address, read in `shared/brand.mjs`; any other value reads as unset |
 
 ### 5.2 Engine & models — T3
 
@@ -230,7 +231,7 @@ Per-lane `CLEAROTRON_NATIVE_LANGUAGE_<XX>` — `zh`, `ja` and `ko` all work (`LA
 `driver/jx-lanes.mjs`); default on, set `0` to kill one lane — plus `CLEAROTRON_JX_SERP_DEADLINE_MS`.
 `CLEAROTRON_JX_SERP_GRID`, `CLEAROTRON_JX_NATIVEREAD` and `CLEAROTRON_JX_CONSUME` were **deleted by item 8**
 under ADR-0002: each was off here and on in production, so the shipped default described a
-configuration nobody ran. The slices now run on conditions a client can already see.
+configuration nobody ran. The slices now run on conditions a requester can already see.
 
 `CLEAROTRON_KNOCKOUT_MODE`, `CLEAROTRON_JX_LANES` and `CLEAROTRON_RECIPES_MODE` were **RETIRED 2026-07-27** and
 have no reader. Depth availability is decided by `BUILT` (`driver/search-policy.mjs`) and the wired
@@ -260,13 +261,13 @@ bodies to one file and restores the unbounded growth the move removed),
 `PROFILE_REPO_ROOT`, `RECIPE_REPO_ROOT`, `CLEAROTRON_OAUTH_BRIDGE` (module-relative),
 `OAUTH_BRIDGE_CREDS_DIR`, `OAUTH_BRIDGE_CLIENT_NAME`.
 
-`PROFILE_DIR` **left this list.** The customer store is named once, by
+`PROFILE_DIR` **left this list.** The company store is named once, by
 `CLEAROTRON_CUSTOMERS_DIR`, and resolved through `shared/customer-store.mjs` for the settings
 surface and the runs alike. It is not accepted as a fallback: a box setting only the retired name
 would otherwise pull the settings surface onto a second store, which is the split that issue
 closed. It still appears in `env-set-in-production.txt` because production is measured, not
 edited — that box runs pre-rebuild code and genuinely still sets it.
-| `CLEAROTRON_JX_SUBCLASS_DB` | unset ⇒ the similar-group lookup REFUSES by name | Path to `similar-groups.db`, built by `node providers/jx-subclass/load-public.mjs` from the committed `public/` tables. Not committed (the office sources permit redistributing the data, not their prose), so a deployment builds it. Unset or missing is a refusal, never an empty answer: `node:sqlite` creates an empty file on open and every lookup over it would read as "no similar groups" — a false clear in the offices a Western client can least check |
+| `CLEAROTRON_JX_SUBCLASS_DB` | unset ⇒ the similar-group lookup REFUSES by name | Path to `similar-groups.db`, built by `node providers/jx-subclass/load-public.mjs` from the committed `public/` tables. Not committed (the office sources permit redistributing the data, not their prose), so a deployment builds it. Unset or missing is a refusal, never an empty answer: `node:sqlite` creates an empty file on open and every lookup over it would read as "no similar groups" — a false clear in the offices a Western company can least check |
 
 ### 5.7 Delivery & comms — T3/T4
 
@@ -300,10 +301,10 @@ set), `TRADEMARK_MCP_TOKEN_SECRET` (+`TRADEMARK_MCP_TOKEN_SECRET_PREVIOUS` rotat
 only**; the portal refuses to start without it — see [docs/SECURITY.md](../SECURITY.md)).
 
 **Scrub guard (test-time only — never read on a run path, and outside the five tiers above).**
-`CLEAROTRON_IDENTIFIER_BLOCKLIST` points at `identifier-blocklist.json` in the customer-config store: the
-retired customer/mark roster the scrub guard matches on, kept out of the product repo because the list
-of names *is* what the guard protects. Unset is a SUPPORTED mode, not a degraded one — the guard runs
-on synthetic sentinels built into the guard, which is how the public repository runs
+`CLEAROTRON_IDENTIFIER_BLOCKLIST` points at `identifier-blocklist.json` in the config store: the
+retired roster of real companies and marks the scrub guard matches on, kept out of the product repo
+because the list of names *is* what the guard protects. Unset is a SUPPORTED mode, not a degraded one —
+the guard runs on synthetic sentinels built into the guard, which is how the public repository runs
 it. Set-but-unreadable, malformed, or below the size floor **throws**: a truncated table reads as a
 smaller blocklist, and a smaller blocklist reads as a cleaner repo. **Whether the real table is required
 is the CALLER's declaration, never the environment's**: `publication-scan.mjs` asks for it in its own
@@ -386,7 +387,7 @@ to be written out.
 | recipe service | `RECIPE_OIDC_ISSUER` | `RECIPE_JWKS_URL` | `RECIPE_EMAIL_CLAIM` | `RECIPE_AUTH_HEADER` |
 | client MCP origin | `CLIENT_MCP_OIDC_ISSUER` | `CLIENT_MCP_JWKS_URL` | `CLIENT_MCP_EMAIL_CLAIM` | `CLIENT_MCP_AUTH_HEADER` |
 
-Each is T4, each is optional, and each unset falls back exactly as the two older sets do — the client
+Each is T4, each is optional, and each unset falls back exactly as the two older sets do — the client MCP
 row to the staff face's matching value first (`TRADEMARK_MCP_OIDC_ISSUER`, `TRADEMARK_MCP_JWKS_URL`,
 `TRADEMARK_MCP_EMAIL_CLAIM`, `TRADEMARK_MCP_AUTH_HEADER`), then to the shapes derived from
 `CF_ACCESS_TEAM` for whichever JWT-fronting proxy the deployment runs.
@@ -419,7 +420,7 @@ replayed as the other. First start in local mode mints a passphrase and prints i
 byte-for-byte the behaviour that shipped before the name existed, dev bypass included; `token` requires
 a valid HMAC-signed scoped access key on **every** request and runs no auth proxy at all. An
 unrecognised value is fatal. `token` is the far end of the local install's Start button — the portal
-holds a verb-scoped, account-capped ops key and this door demands it — and it is **not** a bypass:
+holds a verb-scoped, company-capped ops key and this door demands it — and it is **not** a bypass:
 `lib/http-handler.mjs` refuses outright to build it alongside `TRADEMARK_MCP_AUTH_DISABLED`, because a
 synthetic identity would answer before the mandatory key ever ran. The mode is loopback-only (an ops key
 travels in a header or the query string), requires `TRADEMARK_MCP_ALLOWED_HOSTS` exactly as the
@@ -495,7 +496,15 @@ origin; all portal config lives server-side in portal-service.
 
 These are read by the release workflow and by nothing a deployment runs. They are listed here because a
 name absent from this register is a name nobody can look up, not because an operator has any reason to set
-one — and setting either on a box does nothing at all.
+one — and setting any of them on a box does nothing at all.
+
+`ACTIONS_APPROVE_TOKEN` (unset) — a GitHub token with Actions read and write, used to approve the
+version pull request's parked CI run so that a cut does not wait for someone to click. That run is
+authored by the repository's own Actions bot and GitHub parks bot-authored runs; the built-in token
+cannot release one, because self-approval is blocked deliberately. Unset is the ordinary case: the
+script names the absent token and exits successfully, and the run waits for a person as before.
+Actions write is wider than approving — it also dispatches workflows, cancels any run in the
+repository and deletes run logs — so it is worth rotating on the same schedule as a deploy key.
 
 `CLEAROTRON_CUT_REF` (default `HEAD`) — which ref the cut decision reads the version from. The jobs that
 ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref
@@ -515,8 +524,8 @@ change. The product's known mirror classes:
 
 | Value class | Copies (by design) | Break mode if they diverge |
 |---|---|---|
-| CF Access team / AUD / domain gates | edge (dashboard) + each fronted unit's inline env | staff or client lockout, service by service |
-| `TRADEMARK_MCP_TOKEN_SECRET` | EnvironmentFile + any integrator-hosted artifacts-MCP env block | run-bound client tokens fail verification |
+| CF Access team / AUD / domain gates | edge (dashboard) + each fronted unit's inline env | staff or company lockout, service by service |
+| `TRADEMARK_MCP_TOKEN_SECRET` | EnvironmentFile + any integrator-hosted artifacts-MCP env block | run-bound `user` tokens fail verification |
 | Register-provider credentials | EnvironmentFile + integrator plugin config (when both consume the provider) | one consumer silently unauthenticated |
 | Profiles/skills store paths | EnvironmentFile + service unit files (+ integrator MCP env) | roster-mismatch class (the PR #14 incident) |
 | Pool root | code default + units + web-server file root (+ integrator MCP env) | reports publish where nothing serves |

package/docs/architecture/05-customer-profiles.md

@@ -1,22 +1,22 @@
-# 05 — Customer Profiles
+# 05 — Company Profiles
 
 > Part of the architecture pack (`docs/architecture/`). The driver's module tree and the headless
 > integrator contract are in [`driver/README.md`](../../driver/README.md).
-> This chapter describes the profile *mechanism*. Real customer bundles load from an external store
-> via `CLEAROTRON_CUSTOMERS_DIR` and no customer is named here; the package ships `generic` and the demo
-> brand owner, and the repository holds three further synthetic profiles for the test suite — see
+> This chapter describes the profile *mechanism*. Real company bundles load from an external store
+> via `CLEAROTRON_CUSTOMERS_DIR` and no real company is named here; the package ships `generic` and the
+> demo company, and the repository holds three further synthetic profiles for the test suite — see
 > [`driver/profiles/`](../../driver/profiles/).
 
-One engine, never forked — three layers. The reasoning core is shared by every client; the client
+One engine, never forked — three layers. The reasoning core is shared by every company; the company's
 context sharpens judgment without ever overriding it; the delivery layer shapes presentation only.
-The profile system is where that principle is *enforced*, not just stated: every per-client knob is
+The profile system is where that principle is *enforced*, not just stated: every per-company knob is
 either consumed by named code or rejected at load, and configuration that attempts to move a legal
 rating is refused by pattern guards and by stage-level firewalls.
 
 ## The bundle
 
-A customer = one git-owned JSON file `profiles/<key>.json`, plus optionally: a prose context pack
-(`<key>.context.md`), a per-customer rating framework pair in `skills/prelim-search/`
+A company = one git-owned JSON file `profiles/<key>.json`, plus optionally: a prose context pack
+(`<key>.context.md`), a per-company rating framework pair in `skills/prelim-search/`
 (`risk-framework-<key>.md` + its `.manifest.json`, plus worked examples), and per-engagement
 project overlays under `profiles/projects/<key>/`.
 
@@ -27,25 +27,25 @@ that reads it in `FIELD_CONSUMERS`, and CI asserts the manifest and the key list
 | Key | Layer | What it drives |
 |---|---|---|
 | `name` (required) | identity | Anchor for the self-exclusion gate (`applicantMatchesProfile` — word-boundary containment, so "Company" matches "Company Corporation" but not "Companyish Ltd") |
-| `matchDomains[]` | identity | Forwarder-domain fallback resolution; cross-file overlap is a load error (directory order must never decide a customer) |
+| `matchDomains[]` | identity | Forwarder-domain fallback resolution; cross-file overlap is a load error (directory order must never decide a company) |
 | `platforms[]` (required) | structural | The store domains the marketplace grid sweeps, verbatim — dictated into the worker spec and enforced by the receipts join. Bare domains only, no `"web"` (the general-web cell is implicit), no duplicates: a one-character slip bricks every run under the profile, so load guards are strict |
 | `defaultClasses[]` / `defaultJurisdictions[]` | structural | Matter-frame defaults when the request names none |
-| `selfExclusionOwners[]` | structural | Never flag the client against itself — seeded only when the job's applicant *is* the profile customer |
+| `selfExclusionOwners[]` | structural | Never flag the company against itself — seeded only when the job's applicant *is* the profile's company |
 | `marketplaceDensity` | structural | `sparse` (default) or `dense` — selects the grid cell budget (98 vs 16 cells/call, both calibrated from real truncation incidents) |
 | `industry` | context | Sector context in the matter frame — context, never a rule |
 | `riskAppetite` | context | Prose posture only; reaches **curation stages only**, never synthesis |
 | `delivery` | delivery | `{email: "summary", privileged: bool, style: prose, template: closed-enum}` — presentation only. `email` is inert as of 2026-07-28 (every run gets a cover note); `"table"` is accepted-but-retired so stored profiles keep loading |
-| `frameworkPath` | rating authority | The customer's own risk framework deck; absent ⇒ the Generic default rates the matter ("nothing in between") |
-| `workedExamplesPath` | context | Per-customer synthesis depth target |
+| `frameworkPath` | rating authority | The company's own risk framework deck; absent ⇒ the Generic default rates the matter ("nothing in between") |
+| `workedExamplesPath` | context | Per-company synthesis depth target |
 | `defaultProduct` | entitlement | Which search runs when a request names none (`search-policy.mjs`). May be unset — a clearance that names no product is then named by its own resolved territories |
-| `allowedRecipes[]` | entitlement | The closed menu of searches this account may trigger; absent ⇒ everything allowed. Non-empty when present |
+| `allowedRecipes[]` | entitlement | The closed menu of searches this company may trigger; absent ⇒ everything allowed. Non-empty when present |
 | `jxPolicy` | entitlement | The native-language deepening posture (declared lanes, escalation, provider stance) — policy, never capability. Frozen into the run sidecar so a resume keeps it |
-| `runCaps` | admission | Per-account admission caps `{maxQueued?, dailyRuns?, monthlyRuns?}`, integers 1–10000, at least one set. Enforced at the runner's claim chokepoint for **both** intake doors (email and portal) — the run-slot cap does not bound a client that can trigger its own searches. **Two behaviours it is worth knowing before you rely on a cap** — see below |
+| `runCaps` | admission | Per-company admission caps `{maxQueued?, dailyRuns?, monthlyRuns?}`, integers 1–10000, at least one set. Enforced at the runner's claim chokepoint for **both** intake doors (email and portal) — the run-slot cap does not bound people who can trigger their own searches. **Two behaviours it is worth knowing before you rely on a cap** — see below |
 
 **Two `runCaps` behaviours to know before relying on a cap** (`checkRunCaps`, `driver/runner.mjs`):
 **a cap written onto `generic` does nothing** — it is exempt by design, so a long-lived credential
-pointed there spends without limit; and a client run with no `dailyRuns` gets
-`DEFAULT_CLIENT_DAILY_RUNS`, not unlimited.
+pointed there spends without limit; and a run a company's own people start with no
+`dailyRuns` gets `DEFAULT_CLIENT_DAILY_RUNS`, not unlimited.
 
 **Derived, never stored** (storing either is its own louder load error): the grid floor
 `minCellsPerVariant = platforms.length + 1` and `batchSize = gridCellBudget / floor`.
@@ -56,7 +56,7 @@ never sees it): curated background facts, standing concerns, prior-matter learni
 conditionals are rejected at load; the fix is to rephrase the rule as a concern or question. It
 feeds `report-overview` as context that "NEVER changes a band" and never reaches synthesis.
 
-**The framework layer** (`framework.mjs`) is where per-client rating vocabulary lives. The
+**The framework layer** (`framework.mjs`) is where per-company rating vocabulary lives. The
 framework itself is a prose deck the model reasons *with*; the code-side manifest
 (`<framework>.manifest.json`) carries **vocabulary and order only** — 2–8 ordered bands, each
 `{label, tone}`, no digits in labels ("a numbered band is a score in disguise"), and structurally
@@ -64,8 +64,8 @@ framework itself is a prose deck the model reasons *with*; the code-side manifes
 CI-linted, every profile's framework selection must resolve to a manifest, and bands-shaped decks
 are checked to carry no legacy scoring machinery (`test/framework-lint.test.mjs`).
 
-> **Per-customer decks legitimately diverge, and no test forbids it.** There is no
-> "doctrine-lockstep" check keeping rating tables byte-identical across customer frameworks: the
+> **Per-company decks legitimately diverge, and no test forbids it.** There is no
+> "doctrine-lockstep" check keeping rating tables byte-identical across company frameworks: the
 > framework in force is what *rates* the matter, so divergence is the point. The integrity guarantee
 > is elsewhere — closed manifests (vocabulary only), the anti-rule guards below, and the
 > framework-lint suite (`test/framework-lint.test.mjs`). Code comments in `stages.mjs` still
@@ -76,19 +76,19 @@ split 8/8 and every future field must choose a side (`PROJECT_KEYS ∪ CUSTOMER_
 KNOWN_PROFILE_KEYS`, asserted by test). **Overlayable (8):** platforms, defaultClasses,
 defaultJurisdictions, marketplaceDensity, delivery, riskAppetite, industry, defaultProduct — a
 distinct engagement legitimately runs a different product and different marketplaces.
-**Customer-only (8):** name, matchDomains, selfExclusionOwners, frameworkPath, workedExamplesPath,
-allowedRecipes, jxPolicy, runCaps — identity, rating authority and entitlement stay whole-customer,
-and a project that could widen its own caps would hollow out the customer's. Effective resolution
-merges project → customer → generic with a per-field `origins` map frozen into the run.
+**Company-only (8):** name, matchDomains, selfExclusionOwners, frameworkPath, workedExamplesPath,
+allowedRecipes, jxPolicy, runCaps — identity, rating authority and entitlement stay whole-company,
+and a project that could widen its own caps would hollow out the company's. Effective resolution
+merges project → company → generic with a per-field `origins` map frozen into the run.
 
 ## Resolution and the frozen sidecar
 
 ```mermaid
 flowchart TD
     J["job arrives (queue file)"] --> PK{"job.profileKey<br/>names a roster key?"}
-    PK -- yes --> P1["that customer wins<br/>(intake AI resolved it)"]
+    PK -- yes --> P1["that company wins<br/>(intake AI resolved it)"]
     PK -- no --> FD{"forwarderDomain matches<br/>a profile's matchDomains?"}
-    FD -- yes --> P2["domain-matched customer"]
+    FD -- yes --> P2["domain-matched company"]
     FD -- no --> P3["generic (required fallback)"]
     P1 --> PROJ{"job.projectKey?"}
     P2 --> PROJ
@@ -110,10 +110,10 @@ Three rules make this trustworthy:
   profiles/ edit mid-run can never change a live run's floor or platforms; resume/experiment
   and every validator read the same immutable file; a corrupt sidecar crashes loudly. `profileSha`
   (canonical-JSON sha256) makes "which profile/framework rated this run" verifiable by recompute.
-  A mid-run late-bind of the customer re-classifies findings only — it never re-resolves the
+  A mid-run late-bind of the company re-classifies findings only — it never re-resolves the
   profile.
-- **An unbound run can never be presented customer-framed.** No key + no domain ⇒ generic ⇒ neutral
-  delivery (no client table, no privileged header) — pinned by test.
+- **An unbound run can never be presented as any company's.** No key + no domain ⇒ generic ⇒ neutral
+  delivery (no review table, no privileged header) — pinned by test.
 
 ## The guardrails
 
@@ -124,7 +124,7 @@ Three rules make this trustworthy:
 | **Anti-threshold guard** | `riskAppetite` (and context pack, and delivery style) reject numeric/threshold/rule shapes at load — percentages, comparison operators, "threshold", level/composite cutoffs, imperative ratings | `profiles.mjs` |
 | **The D1 firewall** | Stage messages decide which stage *sees* what: synthesis gets framework + worked examples and **no** appetite/pack/style; the three curation stages get them labelled "emphasis only / NEVER changes a band" | `stages.mjs` |
 | **Framework manifest constraints** | Vocabulary + order only; no digit labels; closed keys; 2–8 bands; deck⇄manifest lint | `framework.mjs`, `test/framework-lint.test.mjs` |
-| **Freeze completeness** | A configured field must be carried by `freezeProfile` or it is silently never applied — the exact 2026-06-19 bug (frameworkPath dropped from the freeze quietly rated two customers under the Generic default); regression-pinned | `pipeline.mjs`, `test/framework-freeze.test.mjs` |
+| **Freeze completeness** | A configured field must be carried by `freezeProfile` or it is silently never applied — the exact 2026-06-19 bug (frameworkPath dropped from the freeze quietly rated two companies under the Generic default); regression-pinned | `pipeline.mjs`, `test/framework-freeze.test.mjs` |
 
 Honest boundary: the regex guards are conservative-reject and *necessary, not sufficient* — a
 pure-prose rule can pass them; the evaluation layer (reference library / review) is the catch for
@@ -137,7 +137,7 @@ A small loopback HTTP service (`profile-service.mjs`, systemd user unit, `PROFIL
 which carries the deployment's own directories and is therefore part of a deployment rather than of
 this source tree.
 
-- **Endpoints**: roster list, per-customer view (config + derived values + framework box), validate
+- **Endpoints**: roster list, per-company view (config + derived values + framework box), validate
   (server-side dry run), save (validated **auto-commit** — creates or updates the JSON + context
   pack and commits authored as the signed-in identity), health (unauthenticated liveness), plus the
   project endpoints.
@@ -150,13 +150,13 @@ this source tree.
   (a body-supplied author is ignored); every write re-runs the *same* load-time validators the
   driver uses, so the UI can never persist a profile the driver would reject; and
   `frameworkPath`/`workedExamplesPath` are **code-owned** — the on-disk value always wins because a
-  2026-07-04 UI save once silently stripped both fields and flipped two customers to the Generic default
+  2026-07-04 UI save once silently stripped both fields and flipped two companies to the Generic default
   framework (`preserveCodeOwned`, `profile-service.mjs`).
 - **Governance posture**: UI saves are validated auto-commits with no PR gate. Recovery is
   `git revert` plus the audit log (`profiles/_audit.log`, git-tracked). In-flight runs are
   unaffected (sidecar freeze); changes ship to the next run.
 
-## Onboarding a new client — the runbook
+## Onboarding a new company — the runbook
 
 **Path A — git PR** (the bespoke-engagement default):
 
@@ -173,7 +173,7 @@ this source tree.
    report reads right.
 5. Merge + deploy.
 
-**Path B — the config UI**: sign in through CF Access → "+ New customer" → fill the form →
+**Path B — the config UI**: sign in through CF Access → "+ New company" → fill the form →
 "Check first" (dry-run validate) → "Save" (validated auto-commit + audit line).
 
 **Either path, afterwards:**
@@ -181,9 +181,9 @@ this source tree.
 - **Routing**: intake stamps `job.profileKey` (the primary selector); optionally add
   `matchDomains` for forwarder-based fallback. A profile with empty `matchDomains` is reachable by
   profileKey only.
-- **Per-customer framework** (optional; git-only, legal-team work — the UI cannot set it): add the
+- **Per-company framework** (optional; git-only, legal-team work — the UI cannot set it): add the
   deck + manifest + worked examples under `skills/prelim-search/`, set the two paths in the profile
-  JSON via git. Until then the customer rates under the Generic default.
+  JSON via git. Until then the company rates under the Generic default.
 - **Per-engagement overlay** (optional): `profiles/projects/<key>/<slug>.json` with the 8
   overlayable keys; intake stamps `job.projectKey` to select it.
 

package/docs/architecture/06-operations-runbook.md

@@ -85,7 +85,7 @@ properties below, each of which was learned the expensive way:
    them; silent auto-promotion twice resurrected intentionally deleted files. A skill relocated into
    the driver tree is relocation, not drift.
 4. **Driver block** — install dependencies, copy the seven unit files + `daemon-reload`,
-   install/enable/restart the sibling services (profile-service, client access/MCP), and
+   install/enable/restart the sibling services (`profile-service`, `client-access`, `client-mcp`), and
    **pre-create the queue dirs and the outbox**: an inotify `.path` watch on a directory that does
    not exist never fires.
 5. **Restart the gateway last**, with no live run and the triggers stopped, then re-enable the four
@@ -260,37 +260,37 @@ pre-change telemetry directory), because the resolver reads the file that is the
 ## Access control and instance isolation
 
 Three capabilities you meet once the engine produces reports other people want to see. Each is off,
-or single-tenant, until you configure it.
+or shared by everyone, until you configure it.
 
-### Tenant grants — who may see which runs
+### Organisation grants — who may see which runs
 
-`CLEAROTRON_ACCESS_FILE` names one JSON file: the guest list. It maps **tenants** (an organisation) to the
-**accounts** they may see, and users within a tenant to a subset of it. An account key is a
-`profileKey` — the customer bundle a run froze at start (§4) — so a grant is expressed in the same
+`CLEAROTRON_ACCESS_FILE` names one JSON file: the guest list. It maps **organisations** (`tenants`) to the
+**companies** (`accounts`) they may see, and people within an organisation to a subset of it. A company
+key is a `profileKey` — the company bundle a run froze at start (§4) — so a grant is expressed in the same
 vocabulary as the runs it filters.
 
 **Unset means enforcement is off for the MCP faces** — whoever gets through your door sees every run.
 **It is not a valid state for the portal, which refuses to start without a guest list**; the access
-model is stated once, in [docs/SECURITY.md](../SECURITY.md). Setting the variable turns account scoping
+model is stated once, in [docs/SECURITY.md](../SECURITY.md). Setting the variable turns company scoping
 on for **every face at once** — the portal, the MCP read face, the client face, and ops tokens. There is
 no half-enforced state and no per-surface switch to forget.
 
-Resolution: the signed-in email is matched against each tenant's `users` map, by exact address or by
-a `*@domain` wildcard; a user value of `"*"` means the tenant's whole grant; an address appearing in
-several tenants gets the union. An authenticated address matching nothing is granted nothing — it
-signs in and sees an empty world. That is deliberate. Signing in is not being enrolled.
+Resolution: the signed-in email is matched against each organisation's `users` map, by exact address or
+by a `*@domain` wildcard; a user value of `"*"` means the organisation's whole grant; an address
+appearing in several organisations gets the union. An authenticated address matching nothing is granted
+nothing — it signs in and sees an empty world. That is deliberate. Signing in is not being enrolled.
 
 **A file that is set but unreadable throws rather than failing open.** A missing path, malformed JSON,
 or a file with no `tenants` object stops the process and names the reason. Keep that in mind when you
 move the file: a guest list you configured and then broke must never resolve to "admit everybody".
 
-`examples/grants.example.json` is a working file over the synthetic demo customers this repo ships.
+`examples/grants.example.json` is a working file over the synthetic demo companies this repo ships.
 Copy it, point `CLEAROTRON_ACCESS_FILE` at your copy, sign in as one of its addresses, and you see
-exactly that tenant's accounts. Then delete it and write your own — it names nobody real, which also
+exactly that organisation's companies. Then delete it and write your own — it names nobody real, which also
 means it grants nothing you have.
 
 `npx clearotron start` (§6) writes an empty roster (`{"tenants": {}}`) into its state directory: your own staff
-address is admitted, no client is enrolled, and enforcement is already on.
+address is admitted, nobody else is enrolled, and enforcement is already on.
 
 ### Ops tokens — a credential for the verbs that spend
 
@@ -308,8 +308,8 @@ node mcp-server/mint-token.mjs --scope ops --sub <principal-name> \
   tokens are then distinguishable in the log; one shared token makes them permanently indistinguishable.
 - `--verbs` is a least-privilege allowlist of write tools. A connector minted without `stop_run`
   cannot call it — the check sits at the one chokepoint every tool call passes, not in each tool.
-- `--accounts` caps the token to a set of account keys, so a trial integration can start demo
-  searches and never a real customer's.
+- `--accounts` caps the token to a set of company keys, so a trial integration can start demo
+  searches and never a real company's.
 - The token is printed once and stored nowhere. Losing it means minting another.
 
 **Revoking one.** Every mint prints a `jti`. Write that line into the file named by
@@ -338,11 +338,11 @@ That makes the environment the whole isolation boundary, so set it to make a tes
 | Axis | Variables | Why it is structural |
 |---|---|---|
 | Data plane | `CLEAROTRON_REPORTS_DIR`, `CLEAROTRON_WORK_DIR`, `CLEAROTRON_QUEUE_DIR`, `CLEAROTRON_OUTBOX_DIR` | separate directories mean a test run cannot publish into the live archive even by mistake |
-| Customer configs | `CLEAROTRON_CUSTOMERS_DIR`, `CLEAROTRON_INSTRUCTIONS_DIR` **unset** on the test instance | it then resolves the repo's synthetic demo customers and cannot read a real bundle |
+| Company configs | `CLEAROTRON_CUSTOMERS_DIR`, `CLEAROTRON_INSTRUCTIONS_DIR` **unset** on the test instance | it then resolves the repo's synthetic demo companies and cannot read a real bundle |
 | Engine | the running engine's binary variable (`CLEAROTRON_CLAUDE_PATH` / `CLEAROTRON_CODEX_PATH`) pointed at `driver/test/mock-claude.mjs` | the mock engine needs no provider credentials, so a test instance can hold none — the strongest form of "spends nothing" |
 | Ports | give the test instance its own for the portal, MCP face and profile service | a default that collides with a live service turns a dry run into a probe of the live one, and it looks like it worked |
 | Auth | `TRADEMARK_MCP_AUTH_DISABLED=1` with `TRADEMARK_MCP_DEV=1` is **loopback-only, enforced in code** | the switch cannot be used to open a remote face |
 
-The strongest isolation is still two instances with their own pool and their own config store. Tenant
-grants above are for the case where one instance must be shared safely — demos, trials, per-user
-scoping inside one firm — not a substitute for this.
+The strongest isolation is still two instances with their own pool and their own config store. Organisation
+grants above are for the case where one instance must be shared safely — demos, trials, per-person
+scoping inside one organisation — not a substitute for this.