clearotron 0.2.4 → 0.3.0-beta.1

package/docs/CLIENT-MCP.md

@@ -45,7 +45,7 @@ accounts their email is granted (`CLEAROTRON_ACCESS_FILE` — the same guest lis
 Enrolment is therefore the portal's: no second credential to mint, rotate or revoke, and revoking portal
 access revokes this with it. **Off unless `CLIENT_MCP_ACCOUNT_ACCESS=1`.**
 
-**Who turns that on. The installer, since 2026-09-03** — owner ruling, settled
+**Who turns that on. The installer, since 2026-09-03** — ruling, settled
 point 2. `render-units.mjs --apply` and `npx clearotron start --background` both write the settings this
 door refuses to start without and then place and enable `clearotron-client-mcp.service`. The settings
 come from one authority, `enablePlan` in `shared/client-door.mjs`, which is also what
@@ -79,7 +79,7 @@ under the report, not just its prose. It projects named structured fields and en
 them — `mcp-server/lib/evidence.mjs` states that there is no code path forwarding free prose, and
 that is the one declared exception to the scrub.
 
-**The audit chain is open by owner ruling, 2026-08-27** ("I don't see why we don't open it or just
+**The audit chain is open by ruling, 2026-08-27** ("I don't see why we don't open it or just
 give it to clients. Ignore the call spend."). The same lawyer who needs the records also has to be
 able to show *how* the answer was reached, so the decision chain is client product now. Unlike the
 evidence layer this one does forward prose — a chain of reasoning is prose — so it is bounded a

package/docs/E2E.md

@@ -6,6 +6,12 @@ How to prove a deployment of this product works end to end, at four cost tiers.
 doubles as the **dev/prod instance split**: a dev instance is just a second env-file pointing every
 data-plane path somewhere isolated — the code is identical.
 
+> **This page is written for a checkout, and the installed package is not one.** The published package
+> deliberately excludes the test tree, so `driver/test/` does not exist in an npm install — Tier 0 and
+> the `$0` mock engine below are reachable only from a clone. Everything from Tier 1 down applies to an
+> installed deployment as written. If a path here starting `driver/test/` is not on your disk, that is
+> the reason, and it is not a mistake in your configuration.
+
 ## Tier 0 — offline, in-repo (already in `npm run test:full`, $0)
 
 `driver/test/pipeline.anthropic.test.mjs` runs the full clearance pipeline on the production engine
@@ -38,10 +44,10 @@ CLEAROTRON_WORK_DIR=/home/you/trademark-dev/workspace
 CLEAROTRON_REPORTS_DIR=/home/you/trademark-dev/pool
 CLEAROTRON_OUTBOX_DIR=/home/you/trademark-dev/outbox
 CLEAROTRON_AI=anthropic-agent
-CLEAROTRON_CLAUDE_PATH=/home/you/clearotron/driver/test/mock-claude.mjs   # $0 mock engine; ABSOLUTE — see below
+CLEAROTRON_CLAUDE_PATH=/home/you/clearotron/driver/test/mock-claude.mjs   # $0 mock engine; CHECKOUT ONLY, and ABSOLUTE — see below
 MOCK_VERDICT=CLEAR
 MOCK_SKEPTIC=no flags surfaced                          # clean skeptic pass under the mock (quotes optional; both work)
-CLEAROTRON_DATABASE=corsearch                      # REQUIRED, no default (tracker issue 503) — the mock never calls it
+CLEAROTRON_DATABASE=corsearch                      # REQUIRED, no default — the mock never calls it
 CORSEARCH_SESSION_KEY=dev-offline                       # the credential preflight wants it set; never fetches under the mock
 CLEAROTRON_SATPROBE_CODESIDE=0                              # the probe dials the provider; a mock run cannot
 CLEAROTRON_BAND_TRUTH_GATE=0                                # the gate evidences bands against the production call ledger
@@ -51,6 +57,10 @@ CLEAROTRON_CUSTOMERS_DIR=                                    # unset ⇒ the dem
 #   grants file every token-less caller resolves to internal read-all across every customer.
 ```
 
+**From an installed package there is no such file at all** — the test tree is excluded from it, so
+before reading the next paragraph check that the path exists. That check is worth making first because
+the failure below looks the same and has a different cause.
+
 `CLEAROTRON_CLAUDE_PATH` must be absolute, and this is the one that catches everybody: the engine child is
 spawned with the RUN DIRECTORY as its cwd, so`driver/test/mock-claude.mjs` is looked for
 *inside the run* and never found. A run now refuses at preflight, before it creates a run directory,

package/docs/ONBOARDING.md

@@ -41,7 +41,7 @@ store, and writes nothing — so the first real run is one you have already read
 
 ## The framework is always set, and the output says which one
 
-Owner ruling, 2026-08-29: the risk framework is mandatory at onboarding, with a default backup so
+Ruling, 2026-08-29: the risk framework is mandatory at onboarding, with a default backup so
 onboarding is never blocked. The command therefore sets a framework on every bundle it writes, and
 prints which one it used.
 

package/docs/PORTAL.md

@@ -19,11 +19,12 @@ enrolment — and none of it is done by installing this repo.
 
 ## The model
 
-| Who | Sees |
+| Who | Sees and does |
 |---|---|
-| Staff (email domain ∈ `PORTAL_STAFF_DOMAINS`) | everything, with an explicit **acting-for** account on scoped routes (never an implicit firm-wide default) |
-| Enrolled client (email in the grants file) | exactly their accounts: their searches, their runs, their released client reports |
-| Anyone else | 403 at the door; cross-account probes read as **404** (existence never leaks) |
+| A person with access to everything | every organisation, company and person, naming a company on scoped routes (never an implicit install-wide default) |
+| A person with access to an organisation or a company | everything below those points: its companies and their runs and reports, and — for an organisation — its Generic |
+| Run clearances · Manage | the two switches each person holds: start and stop clearances; add people, add companies and change settings — both inside the person's access |
+| Anyone else | 403 at the door; probes outside a person's access read as **404** (existence never leaks) |
 
 The enrolment substrate IS the grants file (`CLEAROTRON_ACCESS_FILE`, [the operations runbook](architecture/06-operations-runbook.md#access-control-and-instance-isolation)
 for the shape and `examples/grants.example.json` for a runnable one) — portal
@@ -33,12 +34,12 @@ whichever door this instance runs, then granted here; the model is stated once i
 [docs/SECURITY.md](SECURITY.md). On a proxied instance that means
 `MCP_ALLOWED_EMAIL_DOMAINS` and/or `MCP_ALLOWED_EMAILS` (no default — the portal
 refuses to start with neither set, and combines the two as a UNION rather than the verifier's default
-intersection) must admit the CLIENT identities as well as the staff domain: the staff domain in the
-domain list, and individually named client addresses in `MCP_ALLOWED_EMAILS` rather than their whole
-domain — admitting a consumer domain wholesale to enrol one client would put every address on it
-through the door, leaving the grants file as the only wall. Untagged and `generic` runs are staff-only on
-every client surface — a run with no account tag belongs to no client, so it is shown to none of them.
-Multi-account clients enter the door normally and pick an account (`/portal/api/me` returns the list).
+intersection) must admit every person in the guest list: your own domain in the domain list, and
+individually named outside addresses in `MCP_ALLOWED_EMAILS` rather than their whole domain — admitting a
+consumer domain wholesale to enrol one person would put every address on it through the door, leaving
+the grants file as the only wall. A run with no company tag is shown only to a person with access to
+everything, and a Generic run only inside the organisation it was filed under. A person with several
+companies enters the door normally and picks one (`/portal/api/me` returns the list).
 The one-shot confirmation store is in memory, which bounds the deployment to **one portal process per
 instance**: a second process would not see the first's CONSUMED jtis, so the one-shot guarantee fails
 OPEN rather than closed — the token itself verifies anywhere (both processes hold the same
@@ -108,7 +109,7 @@ What that command starts, for anyone who needs to drive the portal on its own:
 ```bash
 # the portal with the LOCAL identity source (no CF Access, loopback only)
 PORTAL_AUTH_MODE=local PORTAL_LOCAL_USER=cli@celta.example \
-PORTAL_STAFF_DOMAINS=example-firm.com CLEAROTRON_ACCESS_FILE=$HOME/trademark-dev/grants.json \
+CLEAROTRON_ACCESS_FILE=$HOME/trademark-dev/grants.json \
 PORTAL_SECRET="$(openssl rand -base64 32)" CLEAROTRON_REPORTS_DIR=$HOME/trademark-dev/pool \
 CLEAROTRON_WORK_DIR=$HOME/trademark-dev/workspace node driver/portal-service.mjs
 # → http://127.0.0.1:18802/portal/login
@@ -121,8 +122,8 @@ and restarting mints a new passphrase.
 
 What local mode does **not** change is who sees what. It produces an email address and stops;
 `makePrincipal` and the `assertPrincipal` chokepoint judge it exactly as they judge a
-proxy-verified address, so `PORTAL_LOCAL_USER` must ALSO be enrolled — a staff domain for the
-staff view, a grants row for the client view. Sign in as an address the roster does not know and every
+proxy-verified address, so `PORTAL_LOCAL_USER` must ALSO have an entry in the guest list —
+`"everything": true` under `people` for the whole install. Sign in as an address the roster does not know and every
 page refuses it at the door, which is the correct answer and is warned about at boot. The roster itself
 stays mandatory: local mode has a population of one, and one is still a population.
 

package/docs/SECURITY.md

@@ -10,7 +10,7 @@ here corresponds to shipped behavior; when hardening changes, change this file i
 | Surface | Trust | Guard |
 |---|---|---|
 | stdio MCP (`mcp-server/server.mjs`) | local/full ("ops") | OS user boundary — run it AS the operator account; it is the only surface on which `what_if_run` EXECUTES (`visibleTools` keeps what-if out of the HTTP listing for ops, but the CallTool chokepoint gates on `authorize()` alone, which admits it for any ops token not `--verbs`-scoped) |
-| Client MCP (`mcp-server/http-server-client.mjs`) | signed-in client / account key | a client account's `what_if_run` ENQUEUES rather than executes (owner ruling 2026-08-27) — it never imports the engine, and `driver/whatif-worker.mjs` spawns the sandbox from an OS service process. A confirmation token is unsigned, so the call must ALSO name its `runId`: the account gate keys on it, and `whatIfEnqueue` refuses a token naming a different run. The `model` argument is refused to a client. |
+| Client MCP (`mcp-server/http-server-client.mjs`) | signed-in client / account key | a client account's `what_if_run` ENQUEUES rather than executes (ruling 2026-08-27) — it never imports the engine, and `driver/whatif-worker.mjs` spawns the sandbox from an OS service process. A confirmation token is unsigned, so the call must ALSO name its `runId`: the account gate keys on it, and `whatIfEnqueue` refuses a token naming a different run. The `model` argument is refused to a client. |
 | HTTP MCP (`mcp-server/http-server.mjs`) | authenticated remote | auth-BEFORE-data; fail-closed construction; inner scoped tokens |
 | Report "Ask your AI" links | external report recipients | run-bound `user` tokens minted at publish; client layer only |
 | Dev portal (`driver/dev-portal.mjs`) | dev only | loopback-only (throws on any other host); never production serving |
@@ -33,28 +33,27 @@ Three deployment shapes, and they are the whole set:
 | **Shared or hosted** | `PORTAL_AUTH_MODE=auth-proxy` — any login system in front that authenticates in the browser and forwards a verifiable JWT per request (`cf-access` is the older word for this and still works) | Admit the address at your login system, **then** grant it in the guest list — both halves, always |
 | **Neither configured** | the service refuses to start | — |
 
-Exactly two roles exist: **staff**, admitted by an email-domain rule (`PORTAL_STAFF_DOMAINS`), and
-**client**, admitted by a named grant in the guest list (`CLEAROTRON_ACCESS_FILE`). `makePrincipal` →
-`assertPrincipal` is the only path to a decision and no identity source may reach past it. Grants are
-created in the guest-list file by whoever administers the box — `npm run grant` is the editor for it —
-never from a browser. The file is re-read per request, so a grant lands without a restart.
-
-**A staff domain is a grant to everyone at that domain, so nothing derives one for you.** Every address
-at a listed domain that gets past the sign-in door is staff, and staff sees every brand owner on the
-instance. The install therefore derives `PORTAL_STAFF_DOMAINS` only from a sign-in address that names no
-second person — the `<account>@localhost` form a single-user machine gets by default. Given a real
-address it states the rule it would create, in the words the People & access screen will later use,
-and refuses to write it: set `PORTAL_STAFF_DOMAINS` yourself, or answer the question `clearotron install`
-asks. A webmail or shared provider is refused outright, because a rule built from one admits the public.
-The People & access screen names the setting the rule came from and the file it is written in, so a
-rule can be traced and undone by whoever finds it.
-
-**That check is on the DERIVATION, not on the value.** A `PORTAL_STAFF_DOMAINS` you set yourself is
-taken as written and never classified: `PORTAL_STAFF_DOMAINS=gmail.com` is accepted, and it admits
-everyone at that provider who gets past the sign-in door. This is deliberate — a value someone typed is
-a decision already taken, and the defect being fixed was a rule created with nobody asked — but it means
-the protection is against the accident and not against the configuration. Read what you set, or set
-nothing and answer the question the install asks.
+A person is admitted by their own entry in the guest list (`CLEAROTRON_ACCESS_FILE`) and by nothing
+else. The guest list gives each person access to points on one tree — the whole install, an
+organisation, or one company — and two switches, **Run clearances** and **Manage**. A person sees
+everything below the points they were given and nothing else; both switches off is a person who can read
+and start nothing. In the portal, `makePrincipal` → `assertPrincipal` is the only path to a decision and
+no identity source may reach past it; the connector resolves a key's person through the same function
+(`resolvePerson`, `shared/scope.mjs`), so the two doors cannot disagree about one address. The file is
+re-read per request, so a change lands without a restart. `npm run grant` edits it, and so does anyone
+with Manage from the People page, inside their own access.
+
+**Nothing is admitted by the part of an address after its `@`.** The staff-by-domain rule
+(`PORTAL_STAFF_DOMAINS`) is gone and the setting is ignored. A `*@domain` entry in the guest list still
+names every address at that domain and may hold Run clearances; it may never hold Manage or access to
+everything, and the guest list is refused at load if it tries, because a domain-wide Manage is the staff
+rule by another name.
+
+**Two organisations are invisible to each other because they are sibling branches.** A company belongs
+to exactly one organisation, and the guest list is refused at load if a company is listed under two. A
+clearance run with no company — Generic — is filed under the organisation it was started in and is
+visible only inside it. A Generic run filed before organisations existed is visible only to a person
+with access to everything.
 
 
 - **On the proxy door**, every HTTP request re-validates a JWT from the fronting auth proxy. The
@@ -81,7 +80,7 @@ nothing and answer the question the install asks.
 - Four principal kinds: **ops** (write verbs; automation/operator), **user** (read-only, pinned to
   exactly ONE run — report recipients), **account** (a signed-in client across the accounts their
   identity is granted: the client layer, the evidence layer — `list_evidence` / `list_searches` /
-  `get_search_coverage` — the AUDIT CHAIN (owner ruling 2026-08-27: `read_artifact` over the chain
+  `get_search_coverage` — the AUDIT CHAIN (ruling 2026-08-27: `read_artifact` over the chain
   artifacts named in `ACCOUNT_ARTIFACTS`, `list_findings` on the raw `kind` path, `get_finding`,
   `get_run`, `trace`, `decision_timeline`), WHAT-IF as a queued sandbox job (`what_if_plan`,
   `what_if_run`, `what_if_result`), and the run lifecycle on their own runs, and nothing else. All of it accountSafe and deliberately NOT clientSafe, because a report link is forwardable

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

@@ -173,7 +173,7 @@ timeout shot, warm patch, backoff), the lane-wedge re-dispatch, and the rate-lim
 | `CLEAROTRON_AI_BILLING` | `subscription` (default) \| `api-key` | Billing mode for the selected engine. ONE variable for both, and only the LIVE engine's setting is read — it fills each engine's billing knob, and the engine that is not selected is never consulted. **`anthropic-agent`:** subscription **deletes `ANTHROPIC_API_KEY` from the child env** so `claude -p` uses OAuth subscription credentials (a present key would override them); `api-key` keeps the key — the scale setting and standing fallback. **`openai-agent`:** subscription seeds `auth.json` into the per-run `CODEX_HOME` from `CLEAROTRON_OPENAI_AUTH_FILE` (default `~/.codex/auth.json`) and strips API keys; `api-key` keeps `CODEX_API_KEY`. **Fail-loud either way:** `api-key` with no `ANTHROPIC_API_KEY` / `CODEX_API_KEY` throws, and never silently bills the subscription. The resolved mode is stamped on every stage telemetry row (`engine`, `authMode`, `apiBilled`). |
 | `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH` | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a box that runs both sets both — they were one variable until it met a box needing two different paths. Give it an **absolute** path if the binary is not on `PATH` — stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `npx clearotron doctor` refuses one. |
 | `CLEAROTRON_OPENAI_AUTH_FILE` | `~/.codex/auth.json` | The credentials file seeded into the per-run `CODEX_HOME` under subscription billing. Was exempted from the August 2026 rename as an `openai-agent` internal rather than an install-surface name; the owner's 2026-09-04 ruling **reversed that exemption** and renamed the whole namespace, so it carries the house prefix like everything else. One spelling, no exceptions. |
-| `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` / `CLEAROTRON_OPENAI_MODEL_CHEAP` | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`. | Maps the driver's abstract `opus`/`sonnet`/`haiku` tiers onto the codex ladder, the way the anthropic engine maps onto its own (owner ruling 2026-09-02, superseding the single-model mapping). A tier that cannot hold its stage contract announces itself at that stage — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` in `_driver/<stage>.jsonl` — not at delivery. |
+| `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` / `CLEAROTRON_OPENAI_MODEL_CHEAP` | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`. | Maps the driver's abstract `opus`/`sonnet`/`haiku` tiers onto the codex ladder, the way the anthropic engine maps onto its own (ruling 2026-09-02, superseding the single-model mapping). A tier that cannot hold its stage contract announces itself at that stage — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` in `_driver/<stage>.jsonl` — not at delivery. |
 | ↳ why they are three, and what the old measurement still says | superseded 2026-09-02, not erased | The three defaulted to `sol` alone on a MEASUREMENT, never a placeholder: on 2026-08-11/12, with `SWEEP=gpt-5.6-terra` / `CHEAP=gpt-5.6-luna`, every codex clearance died on structural-output gates — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` — over 2 scenarios × 3 stage families, **byte-identically on retry**, so no retry budget rescued it. That measurement stands for the code and the codex CLI **of that date**, and it is why the judgment tier keeps `sol`. Three weeks of stage-contract work and several codex minor versions sit between it and the 2026-09-02 ruling that split the three. **The symptom to match against this cause is unchanged**: those same three gates, as a fail row in`_driver/<stage>.jsonl`, inside the first few dispatches of a clearance and identical on every retry — a model incapable of a contract is not flaky at it. It reads as an engine bug when the only fault is this configuration. A cheap-tier experiment still belongs in the three constants in `driver/engine/openai-agent.mjs` where a reviewer sees it, not in an untraceable env line. |
 | `CLEAROTRON_DATABASE` | **REQUIRED — no default.** `corsearch` \| `clarivate` \| `signa` \| `euipo` \| `uspto-local` \| `free-tier` | Active register provider — one per run, set in the environment the deploy carries, in every environment including production. There is **no default**: unset resolves to `null` and every use of it throws, so a run refuses at start rather than calling a vendor nobody chose ( — the removed`corsearch` fallback named a vendor the deployment did not choose). Three are paid global sweeps; `euipo` (EU) and `uspto-local` (US) are free single-office sources, and `free-tier` composes those two as one register. Choosing a free value makes every territory outside its coverage a disclosed *deferred* row. Unknown ids throw loudly, and the gather layer throws at stage time for any provider without a built MCP server. |
 | `CLEAROTRON_CODEX_SANDBOX_BYPASS` | unset | `1` runs `codex exec` with its own sandbox helper bypassed, for hosts where that helper cannot spawn. It removes a defence: with it set, the run dir is writable by the seat and only the deny-hook stands between a stage and `_driver/`. Set it because the host forces it, never for convenience. |
@@ -282,9 +282,10 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | Var | Default | Meaning |
 |---|---|---|
 | `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 (owner 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_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 (owner 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 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_ORGANISATION_NAME` | unset | Your organisation's name, written quoted by `npx clearotron install` directly after the 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, renaming is an edit there, and this is not read. 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`. |
 | `PORTAL_LOCAL_CREDENTIAL` | `~/.cordillera/portal-local-credential.json` | Where local sign-in keeps its passphrase DIGEST. `npx clearotron demo` points it inside the demo's own base directory, so a demo mints its own passphrase instead of inheriting 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. |
@@ -293,7 +294,7 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `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. |
 | `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 (owner ruling 2026-08-07), so the comparison script names the variable rather than defaulting anywhere. |
+| `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. |
 
 ### Gates that are OFF by default
@@ -345,7 +346,7 @@ cannot be read as one list.
 
 ### Retired — set these and nothing happens
 
-`tracker issue 1838` deleted the settings below. Nothing in any environment set them, so each became the constant it
+The settings below were deleted. Nothing in any environment set them, so each became the constant it
 had always resolved to. **They are listed because an operator whose `.env` still carries one needs to
 know it is inert** — an unread setting is indistinguishable from a setting that works.
 
@@ -363,6 +364,12 @@ know it is inert** — an unread setting is indistinguishable from a setting tha
 | `CLEAROTRON_SUPPLEMENTAL_PER_CALL` | 12 supplemental queries per call |
 | `CLEAROTRON_WALL_RESCUE_QUIESCE_MS` | 60 seconds waiting for a killed tree to quiesce |
 
+**`PORTAL_STAFF_DOMAINS` is retired differently, because deployments did set it.** Everyone at a listed
+email domain used to be staff. Who may use the portal is now each person's own entry in the grants file
+(`CLEAROTRON_ACCESS_FILE`), with `"everything": true` under `people` for anyone who should see every
+company, and no domain admits anyone. A portal that still finds the setting starts, and says at boot that
+it is ignored and what replaced it.
+
 ## Change management
 
 - **Live env flip (no deploy):** caps, backoffs, feature gates, A/B toggles — edit the deployment's

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

@@ -69,7 +69,7 @@ Recurring confusion, settled: "we configure the MCP servers at the edge" is true
 fills the same three roles, and the product requires none of them by name.
 
 1. **Edge auth (T5, dashboard):** the tunnel routes each public hostname to a loopback port, and a
-   CF Access app decides *who* may reach it (staff domain gate; client per-email policy; dev app).
+   CF Access app decides *who* may reach it (your own domain; outside people per email; dev app).
 2. **Local verification (T4, unit files):** every service *independently re-verifies* the CF Access
    JWT. For that it needs the team + the app's AUD tag — so `CF_ACCESS_TEAM`/`CLEAROTRON_OIDC_AUDIENCE`/
    `MCP_ALLOWED_EMAIL_DOMAINS` appear in unit files as **mirrors of the dashboard**, not a second
@@ -105,12 +105,12 @@ by name in §5 below and in the upgrade table in INSTALL.md.
 who has not read the code. Vendor credentials keep the vendor’s name (`SIGNA_API_KEY`,
 `PERPLEXITY_API_KEY`, `ANTHROPIC_API_KEY`) — that already says who you bought them from.
 
-**THERE IS ONE SPELLING.** The compatibility window that read both closed on 2026-08-26 by owner ruling:
+**THERE IS ONE SPELLING.** The compatibility window that read both closed on 2026-08-26 by ruling:
 no migration, no legacy support. A deployment is REBUILT from the install rather than carried across,
 which is also the only thing that proves the install works for a new reader — a migrated box tests a path
 no new user ever walks.
 
-**A retired spelling is not checked for either** — owner ruling, same day, asked directly. The premise
+**A retired spelling is not checked for either** — ruling, same day, asked directly. The premise
 is what makes the absence correct rather than careless: a machine reaches this code through the install,
 the install writes the names in force, and the boxes that predate the rename are rebuilt rather than
 deployed onto. There is no population left holding the old lines.
@@ -294,7 +294,7 @@ it. Set-but-unreadable, malformed, or below the size floor **throws**: a truncat
 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
 source and refuses by name before it runs a single check if it cannot reach it. There is no switch —
-`CLEAROTRON_REQUIRE_BLOCKLIST` was deleted by owner ruling, because a variable that decides whether a scrub
+`CLEAROTRON_REQUIRE_BLOCKLIST` was deleted by ruling, because a variable that decides whether a scrub
 guard looks for anything real has a silent OFF position, and silent-off is the one state this module
 exists to make impossible: without the table, "matched nothing" and "had nothing to match on" are the
 same green.
@@ -328,7 +328,7 @@ which collided with a co-hosted warm-MCP block, so keep any unit override that n
 `CLIENT_MCP_SESSION_TTL_MS`, `CLIENT_MCP_SESSION_MAX`, `CLIENT_MCP_RATE_PER_MIN`, `CLIENT_MCP_URL`,
 `CLIENT_MCP_TOKEN_ONLY`, `CLIENT_MCP_AUTH_DISABLED` / `CLIENT_MCP_DEV` (dev seams — never set in prod). CF mirrors (T5): `CF_ACCESS_TEAM`, `CLEAROTRON_OIDC_AUDIENCE`,
 `CLEAROTRON_CLIENT_OIDC_AUDIENCE`, `MCP_ALLOWED_EMAIL_DOMAINS`, `MCP_ALLOWED_EMAILS`. Admin services:
-`PORTAL_SERVICE_PORT` (18802) / `PORTAL_SERVICE_HOST`, `PORTAL_STAFF_DOMAINS`, `PORTAL_MCP_URL`,
+`PORTAL_SERVICE_PORT` (18802) / `PORTAL_SERVICE_HOST`, `PORTAL_MCP_URL`,
 `PORTAL_RATE_PER_MIN`, `PORTAL_LOCAL_WORKER` (set only by `bin/start.mjs` when it supervises a worker,
 and what licenses the portal to say a queued job is waiting for one — a deployed instance drains via
 systemd, writes no heartbeat, and must keep saying "waiting to start" rather than invent an alarm),
@@ -363,7 +363,7 @@ catch, so it has to be deliberate. The client door also passes `authHeader` into
 it did not before, so its seam would have been settable and inert.
 
 **Named in full rather than as a prefix**, because a row that abbreviates a family documents nothing an
-operator can search for — and `tracker issue 692`'s own second arm fails exactly that, which is how this table came
+operator can search for — and the rule's own second arm fails exactly that, which is how this table came
 to be written out.
 
 | service | issuer | JWKS | identity claim | token header |
@@ -391,7 +391,7 @@ the test box and production both bind 127.0.0.1 behind a tunnel.
 
 Local mode adds two values and no third: `PORTAL_LOCAL_USER` is the one email address that signs in
 (mandatory in that mode — the service refuses to start without it, and the address must ALSO be enrolled
-in `CLEAROTRON_ACCESS_FILE` or on a staff domain, because signing in is not being enrolled), and
+in `CLEAROTRON_ACCESS_FILE`, because signing in is not being enrolled), and
 `PORTAL_LOCAL_CREDENTIAL` optionally relocates the credential file, which otherwise lives at
 `~/.cordillera/portal-local-credential.json` (mode 0600, never in the repository and never inside the
 pool or the archive). `PORTAL_SECRET` is required in BOTH modes and signs both token families — the

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

@@ -283,7 +283,7 @@ run dir and the ledgers. The auth model (four principal kinds; run-bound client
 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** (owner ruling 2026-08-27). The audit trail is
+**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
 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`

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

@@ -255,6 +255,11 @@ wrong one exits `MODULE_NOT_FOUND` whose last line is the node version: piped th
 almost exactly like a quiet success, and the ritual's own success test — *"and then `git diff` is
 empty"* — is satisfied **precisely when nothing ran**.
 
+**Three of these regen commands live in the test tree, which the published package excludes**, so they
+are runnable from a checkout and not from an install. That is the right boundary — regenerating a
+baseline is a contributor's act — but it is worth saying here rather than leaving a reader to find an
+absent file and diagnose their configuration.
+
 | File | Regen | What it records |
 |---|---|---|
 | `driver/contract-e3-baseline.json` | `node driver/test/contract-e3-baseline.mjs --write` | structure-as-text per stage dispatch and per skill file |

package/docs/configuration.md

@@ -111,6 +111,124 @@ wanted. A framework and its manifest are checked as a pair.
 Alongside it, `workedExamplesPath` sets the analysis depth target — worked clearances calibrated
 under that framework. Absent, the generic set applies.
 
+### Writing your own, step by step
+
+**Nothing here is a code change.** Two files go into your own store; a profile points at one of them.
+
+**1. Write the deck.** A markdown document. It is reasoned *with*, so write it the way you would brief a
+colleague: what each band means, what it turns on, what to do about it. Give **every band a heading of
+its own**, spelled exactly as you will spell it in the manifest, and under each heading write the rungs
+as bold-led bullets:
+
+```markdown
+## High
+
+- **What it is.** A live registration for a similar mark in a class the client will trade in.
+- **What it turns on.** Whether the goods actually overlap, and whether the owner is using the mark.
+- **What to do.** Advise against adoption unless the owner's non-use can be established.
+```
+
+That shape is not decoration. The profile screen extracts what the bands mean from these headings and
+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.
+
+**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.
+
+```json
+{
+  "schema_version": 1,
+  "framework_key": "your-firm-2026",
+  "title": "Your firm's clearance risk framework",
+  "source_deck": "Where this came from, and when it was last reviewed",
+  "entity_label": "the company",
+  "bands": [
+    { "label": "Very High", "tone": "severe" },
+    { "label": "High",      "tone": "high" },
+    { "label": "Moderate",  "tone": "medium" },
+    { "label": "Manageable","tone": "low" }
+  ],
+  "structure": { "kind": "bands" }
+}
+```
+
+Every key above is required and **no other key is allowed** — an unknown one is refused by name rather
+than ignored. `schema_version` is `1`. `framework_key` is lowercase letters, digits and hyphens.
+`bands` runs **most severe first**; that order is the framework's severity order everywhere the engine
+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
+`"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.
+
+**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
+the deck did not do. It creates nothing, rates nothing and contacts nobody.
+
+```
+clearotron framework skills/prelim-search/your-framework.md
+```
+
+```
+Framework: skills/prelim-search/your-framework.md
+  deck      /srv/clearotron-config/skills/prelim-search/your-framework.md
+            read from the configured store
+  manifest  /srv/clearotron-config/skills/prelim-search/your-framework.manifest.json
+            read from the configured store
+
+It declares itself "Your firm's clearance risk framework" (your-firm-2026), a bands-shaped
+framework rating the company.
+
+The ladder, highest risk first:
+  1. Very High        severe
+  2. High             high
+  3. Moderate         medium
+  4. Manageable       low
+
+What the deck defines:
+  ✓ Very High        Advise against adoption; the owner is likely to enforce.
+  ✗ High             the section under this band's heading states no rungs — a bands-shaped
+                     deck writes each rung as a top-level `- **Label.** text` bullet
+
+Not ready:
+  1 of 4 bands are named in the manifest and not defined in the deck. The profile screen shows
+  what the bands mean only when EVERY band is defined, so one miss empties the whole box.
+```
+
+It exits 0 when the two agree and 1 when they do not, so it can gate a deployment. `clearotron
+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
+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.
+
+**Then open the profile screen** for a company using it, and confirm you see the framework's title, your
+band names in your order, and the box explaining what each band means.
+
+### What is checked, and what is not
+
+| | |
+|---|---|
+| The deck file exists | checked, and a run refuses without it |
+| The manifest parses, and its keys and band labels are legal | checked, by name |
+| The deck's headings and bullets match the manifest's bands | checked, by `clearotron framework` — and by the test suite, for every framework this installation can reach |
+| Which file answered when your store and this repository both have one | reported by `clearotron framework`, and written to the log at view time |
+| Whether the rubric is any good | **not checked, and cannot be** |
+
+That last row is the one to hold on to. A framework is reasoned with on every search the company ever
+runs, and nothing reads it for sense. **A framework that is subtly wrong produces confident ratings that
+look exactly like right ones.** Have it read by whoever would sign the advice, before it is pointed at.
+
 ---
 
 ## 3. Client profiles

package/docs/decisions/0004-documentation-structure.md

@@ -26,8 +26,8 @@ at runtime.
   This bounds the set at about 35 front doors rather than 100 stubs, and a stub is what rots.
 - **Decisions go in `docs/decisions/`.** A ruling gets a numbered ADR so the next reader finds it settled.
 - **No hand-kept changelogs, at any level.** Git holds the history, and a hand-kept log rots. A
-  per-directory one was never written and stays banned. **Amended 2026-08-31 (owner ruling on tracker
-  issue 2055: the landed release-pipeline decision is master, and the old doc is cleaned up to match
+  per-directory one was never written and stays banned. **Amended 2026-08-31 (ruling:
+  the landed release-pipeline decision is master, and the old doc is cleaned up to match
   it, never the machinery bent to the doc):** the root `CHANGELOG.md` is the release pipeline's
   MACHINE-COMPILED output — assembled by `scripts/release-version.mjs` from the pending release notes
   when a release is cut, plain-language-gated, and public-facing (the website receives it). It is not

package/docs/decisions/0006-what-the-public-repository-carries.md

@@ -19,7 +19,7 @@ clearance, and change the code. Nothing else.** In particular it carries no prod
 material, no worked internal mechanics for a lane, and no historical narrative.
 
 Four of the five documents above are withheld. They stay in this repository, which is the archive; they do
-not cross at the cut. **`CHANGELOG.md` left this list on 2026-08-31 (owner ruling:
+not cross at the cut. **`CHANGELOG.md` left this list on 2026-08-31 (ruling:
 the landed release-pipeline decision is master).** The 803-word hand-written file this record reviewed was
 already absent; what carries the name now is the release pipeline's machine-compiled, plain-language,
 public-facing changelog — release history a reader of the public repository is meant to have, which the
@@ -38,7 +38,7 @@ neither is on disk, and neither was ever added or deleted in either repository's
 record that names enforcement which was never written is worse than one that names none, because a
 reader stops looking. What follows is what actually holds the line.
 
-**The drop list itself does not ship.** It stays with the archive by owner ruling, 2026-08-31, so the
+**The drop list itself does not ship.** It stays with the archive by ruling, 2026-08-31, so the
 published tree carries no copy — and neither, today, does any other tree. `CUT_RECORD_PRESENT` is false
 everywhere the code runs.
 

package/driver/CHANGELOG.md

@@ -1,5 +1,75 @@
 # clearotron-driver
 
+## 0.3.0-beta.1
+
+### Minor Changes
+
+- f75266d: New: People, in the sidebar for anyone with Manage, lists who can use the installation, and adds a person.
+  
+  Enter their email address, choose what they may do and what they can see, and save. A sentence under the form says what they will and will not see, before you save. They sign in the same way you do; Clearotron issues no passwords.
+  
+  An installation that signs one person in on its own machine cannot hold a second. People says so, and links to how to put a login system in front of it.
+- f75266d: New: Each person now has two permissions, Run clearances and Manage, instead of a staff or client role.
+  
+  A person sees everything below the points they were given: the whole installation, an organisation, or a single company. Someone without Run has no New clearance. Someone without Manage has no People page and cannot add companies.
+  
+  The company menu groups companies by organisation when you can see more than one. Each organisation has its own Generic, listed first and marked Default. The top bar names your organisation when you can see exactly one.
+- f75266d: New: Clearances with no company set up now have a daily allowance per organisation, 20 unless the Generic profile sets another.
+  
+  Anyone with Run clearances on a whole organisation can start them. One organisation's clearances never use up another's, and a person with access to the whole installation is not limited.
+- c4d2768: New: You can now choose which company a clearance is for on the page itself, and set up new companies in the browser.
+  
+  Those screens used to refuse to render until a company was chosen. They told you to pick one at the top left. That is not where the control is when the sidebar is collapsed. They now show you the companies instead. Each one says what it sells, how many marketplaces it covers, and which territories it defaults to.
+  
+  Setting up a company is a page, not a document. It needs a name. Everything else has a default, and the screen says what that default is. It refuses before writing anything, and says why. A name it cannot make a key from, a key already in use, or an email address another company claims. A company you create can run its first search straight away, with no restart, and stop or cancel that search like any other.
+  
+  The product now says company throughout. It used to say brand owner, account, client and customer for the same thing. The firm running the installation is named separately, in the top bar.
+  
+  Companies created through the settings page were saved without a risk framework. Their matters were then rated under the house default, with nothing on screen saying so. Every company created now carries one, and says which.
+- f75266d: New: The setup wizard now asks for the organisation's name after the sign-in address, and the person who installs starts with access to everything.
+  
+  `clearotron grant add` sets a person's two permissions with `--run` and `--manage`; with neither, the person can look and start nothing.
+- f75266d: For operators: Who may sign in is now decided by each person's own entry in the guest list, and nothing else. On a local installation, the next `clearotron start` gives whoever signs in access to everything if the guest list has no `people` section.
+  
+  - For operators: Any other installation with people on it needs one edit to its guest list (`CLEAROTRON_ACCESS_FILE`) before upgrading.
+  - For operators: Anyone admitted because of their email domain needs an entry under a new `people` section: `"everything": true`, `"run": true`, `"manage": true`.
+  - For operators: Each person who starts clearances needs `"run": true`, and each person who adds people or companies needs `"manage": true`. A person with no entry can see what their access covers, and start nothing.
+  - For operators: An organisation whose `accounts` is `"*"` needs the list of companies it holds instead. Until then the portal refuses to start, and names the entry. A company may be listed under one organisation only.
+  - For operators: `PORTAL_STAFF_DOMAINS` is ignored from this version on, and the portal says so at startup.
+  - For operators: After upgrading, sign in to check, and run `clearotron connect` again for each person whose assistant uses a key.
+
+### Patch Changes
+
+- 8ff52d4: Fixed: Installed under a folder named with `#` or `%`, setup's register check now reads the provider's cost instead of calling it unknown. It built the address of the provider's own declaration by hand, and those characters broke it. It now uses the address Node builds, which is also what Windows needs.
+- 350e0ed: New: `clearotron framework <your-framework.md>` reads a risk framework and its manifest, and reports what they declare.
+  
+  Run it before either rates a matter. It prints the ladder in the framework's own order, the company the deck names, and the shape it is. Where the deck and the manifest disagree, it names the band and says what the deck did not do. It creates nothing, rates nothing and contacts nobody, and it exits non-zero when the pair is not ready. `clearotron brandowner add --dry-run` prints the same report.
+  
+  Getting the deck's shape wrong used to fail quietly. The profile screen showed the framework's title and your band colours, and silently omitted the box saying what the bands mean. The new command answers that question directly, using the screen's own read of the deck.
+  
+  Fixed: a framework served from the product's own files, while you have a configuration store set, now says so.
+  
+  Your store is looked in first, and the product's files answer when it is silent. The product ships decks under names you may also have chosen. So a deck that went missing from your store was replaced by ours rather than reported absent. Same band words, different rubric, nothing raised anywhere. The profile screen now writes one line naming what happened, and the new command reports it.
+  
+  Fixed: the house triage ladder's profile page explains its bands again.
+  
+  Its band sections stated their meanings as plain paragraphs, which the screen does not read. Every company without a framework of its own saw band colours and no explanation. The wording is unchanged.
+- cfb9a9f: Fixed: `clearotron doctor` now says which companies your portal's trigger key can start.
+  
+  The key carries a list of the companies it may start runs for. A company added after the key was minted is outside it. Doctor reported the key's expiry and never its coverage. So the one command whose job is to tell you what a machine is configured for said nothing about it.
+  
+  It reads the roster the services read, not the one a command-line process resolves, and it says which. Those two can disagree, and when they do the difference is the whole answer.
+  
+  The line is a note, not a failure. Your portal takes a fresh credential at the start of every call, so a company outside the key is not normally refused. It is refused when the portal cannot take a fresh one, and the line says so and gives you the command to widen the key.
+- ba2899b: Fixed: On reports searched through Signa, each register finding now links to the office's own page for that record, where the office publishes one. Singapore publishes no such page, so its registrations are cited by number, and the report says why. A number that an office's page cannot take is cited the same way.
+- c4d2768: New: The configuration guide now explains how to write your own risk framework, step by step.
+  
+  It gives the manifest in full. It says which fields are required, and what each one may contain. It shows the shape a deck needs for the profile screen to explain your bands.
+  
+  That shape was undocumented, and getting it wrong fails quietly. The screen still shows the framework's title and your band colours. The box saying what the bands mean does not appear at all.
+  
+  The guide also says what is checked and what is not. Nothing reads your rubric for sense. A framework that is subtly wrong produces confident ratings that look exactly like right ones.
+
 ## 0.2.4
 
 ### Patch Changes