clearotron 0.3.0-beta.0 → 0.3.0-beta.1

package/.env.example

@@ -18,7 +18,7 @@
 # and never listed here: CLEAROTRON_KNOCKOUT_MODE, CLEAROTRON_JX_LANES, CLEAROTRON_RECIPES_MODE — if any of the
 # three is still in your .env, delete the line; the pipeline CLI warns on stderr when it sees one.
 #
-# WHERE THE REST WENT (tracker issue 1838). This file used to carry 237 rows and a new reader met 230 variables to
+# WHERE THE REST WENT. This file used to carry 237 rows and a new reader met 230 variables to
 # reach the fourteen they need. The deployment and tuning names — identity, ports, tenancy, timeouts,
 # batch sizes — now live in `.env.deployment.example`. Nothing was dropped: `node scripts/env-audit.mjs`
 # reads BOTH files, and the ratchet that refuses a product variable with no row anywhere reads both too.
@@ -41,8 +41,8 @@
 #     otherwise.
 #   • Where a var takes a NAMED MODE, the comment says so and no other value does anything at all
 #     (CLEAROTRON_SCREEN_GATE_UNNAMED = "enforce"; CLEAROTRON_UNREACHABLE_SENIOR = open-item|clamp).
-#   • `# effect: <class>` above a row DECLARES WHAT CHANGES when that name is changed (tracker issue 1149-12,
-#     ADR-0002). The vocabulary is closed — silent-output-change | disclosed-gate | credential |
+#   • `# effect: <class>` above a row DECLARES WHAT CHANGES when that name is changed
+#     (ADR-0002). The vocabulary is closed — silent-output-change | disclosed-gate | credential |
 #     deployment | tuning | harness — and EFFECT_CLASSES in scripts/env-audit.mjs says what each one
 #     claims. Like `# external:`, the marker must be the LAST comment above its rows and reaches the
 #     contiguous run below it. The environment-governance guard reds on a NEW `CLEAROTRON_*` read by
@@ -76,7 +76,7 @@
 # gateway-bin adapter was a runtime, not a provider choice; removed in the extraction.)
 #
 # TWO adapters are implemented — engine/CONTRACT.md:3 is the accurate statement, and this file said
-# otherwise until tracker issue 547:
+# otherwise until the free-register work corrected it:
 #   anthropic-agent  `claude -p`, off-gateway. The default.
 #   openai-agent     `codex exec`. Built and $0-tested; live verification still pending.
 # Either way the reasoning needs a subscription or an API key of its own — that is separate from every
@@ -99,13 +99,13 @@ CLEAROTRON_CUSTOMERS_DIR=
 # Compute-skills tree the stage prompts resolve `skills/foo/SKILL.md` against. Default = <driverDir>/skills.
 CLEAROTRON_INSTRUCTIONS_DIR=
 # Delivery pool: report.html + audit.xlsx land here (served by Caddy behind Cloudflare Access).
-# REQUIRED — tracker issue 774 removed the code default. Unset, the engine refuses and names this variable instead
+# REQUIRED — the code default was removed. Unset, the engine refuses and names this variable instead
 # of falling back to /srv/trademark-archive, which on a deployed box is real client matter.
 CLEAROTRON_REPORTS_DIR=/srv/trademark-archive
 # Run-slot lock dir. Default = $CLEAROTRON_WORK_DIR/prelim-run-locks. Every run takes a slot here,
 # whether the runner dispatched it or somebody launched it by hand, so this is what bounds concurrency
 # across an install rather than within one process. The portal also reads it to find the worker
-# heartbeat (tracker issue 1721); two installs pointed at one lock dir would share a cap they do not expect to.
+# heartbeat; two installs pointed at one lock dir would share a cap they do not expect to.
 # effect: deployment
 CLEAROTRON_RUN_LOCK_DIR=
 # Delivery outbox dir (instant handoff-mode delivery wake). Default = $CLEAROTRON_WORK_DIR/prelim-outbox.
@@ -114,7 +114,7 @@ CLEAROTRON_OUTBOX_DIR=
 # HEADLESS intake: one explicit queue dir (no agent workspaces needed) — the enqueue CLI + ops-MCP
 # start_run write here and the runner drains it (additive to the workspace scan). See docs/INTAKE.md.
 CLEAROTRON_QUEUE_DIR=
-# REQUIRED, on every deployment including dev (tracker issue 503). Which register vendor gets called and billed:
+# REQUIRED, on every deployment including dev. Which register vendor gets called and billed:
 # corsearch | clarivate | signa | euipo | uspto-local | free-tier. There is NO default — unset, the driver refuses at run start rather
 # than choosing for you.
 #
@@ -134,9 +134,9 @@ CLEAROTRON_QUEUE_DIR=
 #                                           not run beside it (corsearch and clarivate already
 #                                           aggregate both free offices, so a second call buys nothing).
 #
-#   FREE    euipo         the EU register ALONE (tracker issue 546)      — needs EUIPO_CLIENT_ID + _SECRET
-#           uspto-local   the US register ALONE (tracker issue 547)      — needs USPTO_LOCAL_DB (a built index)
-#           free-tier     BOTH, as ONE register (tracker issue 548)      — needs all three of the above
+#   FREE    euipo         the EU register ALONE                  — needs EUIPO_CLIENT_ID + _SECRET
+#           uspto-local   the US register ALONE                  — needs USPTO_LOCAL_DB (a built index)
+#           free-tier     BOTH, as ONE register                  — needs all three of the above
 #
 # Choosing a free value makes every territory outside its coverage a DISCLOSED DEFERRED coverage row.
 # That is the honest trade of running without a subscription, not a defect to work around.
@@ -151,7 +151,7 @@ CLEAROTRON_DATABASE=clarivate
 #   CLEAROTRON_GATHER_SESSION_KEY, CLEAROTRON_GATHER_SESSION_ID, CLEAROTRON_GATHER_AGENT,
 #   CLEAROTRON_REGISTER_CALL_LOG, CLEAROTRON_REGISTER_RECORD_LOG
 #
-# THERE IS NO RETENTION SETTING AND NO CLEANUP JOB (tracker issue 743). CLEAROTRON_REGISTER_LEDGER_MAX_BYTES,
+# THERE IS NO RETENTION SETTING AND NO CLEANUP JOB. CLEAROTRON_REGISTER_LEDGER_MAX_BYTES,
 # CLEAROTRON_REGISTER_LEDGER_KEEP and `npm run prune:ledger` are gone with the rotation tool, because the
 # thing they bounded no longer grows: RECORD BODIES ARE WRITTEN INTO THE RUN'S OWN DIRECTORY
 # (<run>/_driver/register-record-bodies.jsonl), archived with the run and purged with it. Nobody should
@@ -164,19 +164,19 @@ CLEAROTRON_DATABASE=clarivate
 # CLEAROTRON_REGISTER_CALL_LOG is the one that stays box-global: it is one small row per provider call, read
 # ACROSS runs by the provider-usage tally, and it is the independent witness that a run made record
 # fetches at all (so a run whose bodies went missing reports as a failure and not as a clean zero).
-# Leave it unset: the default is ~/trademark/telemetry/register-calls.jsonl (tracker issue 774 — an existing ledger
-# under the pre-tracker issue 774 telemetry directory keeps being read where it sits), and an existing corsearch-named
-# file from before tracker issue 594 is still read where it sits — production is on that filename today, and reading
-# it is not a fault. The vendor-named ENV VARS are gone (tracker issue 605).
+# Leave it unset: the default is ~/trademark/telemetry/register-calls.jsonl (an existing ledger under the older
+# telemetry directory keeps being read where it sits), and an existing corsearch-named file from before
+# the vendor rename is still read where it sits — production is on that filename today, and reading it
+# is not a fault. The vendor-named ENV VARS are gone.
 #
-# tracker issue 1269 — BEING BOX-GLOBAL, IT USED TO COLLECT THE TEST SUITE'S FIXTURE TRAFFIC. A full-suite run on a
+# BEING BOX-GLOBAL, IT USED TO COLLECT THE TEST SUITE'S FIXTURE TRAFFIC. A full-suite run on a
 # dev or test box appended mock provider calls to this same file, and nothing on the rows said so, so
 # every usage pattern, provider comparison and cost read over it silently included them. `npm test`
 # now exports CLEAROTRON_SUITE_TELEMETRY_DIR into its own temp root and the ledgers resolve under that
 # instead. It is set by the test wrapper and is NOT an operator setting: setting it by hand sends a
 # real run's billing rows somewhere the tally never reads.
 #
-# A box upgraded across tracker issue 743 still holds its old global RECORD file. Nothing writes or reads it now; the
+# A box upgraded across the retention change still holds its old global RECORD file. Nothing writes or reads it now; the
 # driver says so once per process on stderr. Archive it with one `mv` when convenient.
 
 
@@ -187,7 +187,7 @@ CLEAROTRON_DATABASE=clarivate
 # subprocess by default so it bills the OAuth SUBSCRIPTION (cheaper), not the API. Keep it set
 # for the gateway + as the api-key fallback (see CLEAROTRON_AI_BILLING).
 ANTHROPIC_API_KEY=sk-ant-...
-# The headless subscription sign-in's token (tracker issue 2070). `claude setup-token` — run on any
+# The headless subscription sign-in's token. `claude setup-token` — run on any
 # machine you can sign in on — prints it; setup captures it by paste. The stage subprocess inherits it
 # untouched in both billing modes (spawnEnv strips only the API key), so this row is the whole
 # mechanism by which a browserless server authenticates the subscription lane.
@@ -202,7 +202,7 @@ CLAUDE_CODE_OAUTH_TOKEN=
 #                                            clean subscription bill, so it cannot serve as the key)
 #
 # `npm run setup` asks this as its own question, adopts the key, and proves the pair with one cheap
-# turn before writing anything (tracker issue 1149 item 5) — so a hand-edit here is the second-best route.
+# turn before writing anything — so a hand-edit here is the second-best route.
 CLEAROTRON_AI_BILLING=subscription
 # The api-key credential for openai-agent. Only read when CLEAROTRON_AI=openai-agent and
 # CLEAROTRON_AI_BILLING=api-key; under "subscription" that engine reads ~/.codex/auth.json instead and
@@ -217,10 +217,10 @@ OPENAI_API_KEY=
 # Azure OpenAI provider creds. RECONSTRUCTED: only $AZURE_OPENAI_DEPLOYMENT is referenced in this
 # repo (as the rendered catalog id); these follow the azure-openai provider convention of the agent
 # platform that consumes them, NOT this repo directly. Verify the exact names against that platform's
-# own configuration at deploy — that config belongs to it and is not in this tree under any name (tracker issue 876).
+# own configuration at deploy — that config belongs to it and is not in this tree under any name.
 # There was never a reader HERE to retire, which is what separates these rows from a stranded one — and
-# the line below is what tells the catalogue guard so (tracker issue 1426).
-# external: the agent platform's azure-openai provider config (tracker issue 876)
+# the line below is what tells the catalogue guard so.
+# external: the agent platform's azure-openai provider config
 AZURE_OPENAI_API_KEY=changeme
 AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
 AZURE_OPENAI_DEPLOYMENT=gpt-5.4
@@ -235,7 +235,7 @@ AZURE_OPENAI_API_VERSION=2024-10-21
 # file — an ENV VAR, not a committed literal, and there is no literal under any spelling to edit.
 #
 # THERE IS NO DEFAULT PROVIDER, and this block said there was until now. Unset, CLEAROTRON_DATABASE
-# resolves to null and every use of it throws at the run door. tracker issue 503 removed the old default for the
+# resolves to null and every use of it throws at the run door. The old default was removed for the
 # reason worth knowing before you leave it unset: an unset variable took Corsearch in silence, and the
 # credential guard could not catch it because both boxes carried CORSEARCH_SESSION_KEY.
 #
@@ -248,7 +248,7 @@ CLARIVATE_API_KEY=changeme
 # Signa.
 SIGNA_API_KEY=changeme
 #
-# USPTO, local (tracker issue 547) — the free US source, and the only one here that is not a paid vendor. TWO
+# USPTO, local — the free US source, and the only one here that is not a paid vendor. TWO
 # variables, and they are needed at different moments, which is why neither substitutes for the other.
 #
 # USPTO_LOCAL_DB — where the register FILE lives. The provider searches this; at SEARCH time there is no
@@ -279,13 +279,13 @@ USPTO_API_KEY=changeme
 # used to imply. There are four products and all four use it, though they behave differently without
 # it and the difference is worth knowing before you diagnose one:
 #
-#   Knockout search           RUNS ANYWAY, and says what it skipped (tracker issue 1223 acceptance 6). The screen
+#   Knockout search           RUNS ANYWAY, and says what it skipped. The screen
 #                             carries the register count probe, so its register half is a whole answer
 #                             without this key: it delivers counts, marks every name for manual
 #                             verification, and states on the report that the open-web half did not
 #                             run. The sweep is NOT ATTEMPTED — nothing is billed and nothing 429s.
 #                             CLEAROTRON_KNOCKOUT_SWEEP_FIXTURES still gives a $0 dev run WITH a sweep.
-#   The three clearances      REFUSE AT PREFLIGHT, before a stage has spent (tracker issue 1149 item 6). All three
+#   The three clearances      REFUSE AT PREFLIGHT, before a stage has spent. All three
 #   (global preliminary,      carry `commonLawGrid: true` and a saved search cannot switch it off
 #    multi-country focus,     (search-policy.mjs), so the deterministic grid sweep always runs, and the
 #    full country)            run door refuses by name — grep the tree for the exact string:
@@ -311,15 +311,15 @@ PERPLEXITY_API_KEY=pplx-...
 # top-up somebody can do in five minutes rather than a defect to diagnose.
 #
 # WITHOUT IT the lane does not silently shrink: every grid cell gaps and the run says so, naming the
-# dominant cause (`SERPAPI_API_KEY absent from driver env`). There is no switch to arm first — tracker issue 1149
-# item 8 deleted it — so any run whose product carries the zh lane needs this key or discloses the gap.
+# dominant cause (`SERPAPI_API_KEY absent from driver env`). There is no switch to turn on first — that
+# switch was deleted — so any run whose product carries the zh lane needs this key or discloses the gap.
 SERPAPI_API_KEY=your-serpapi-key
 
 
 # -----------------------------------------------------------------------------
 # 5. REGISTER / EU  (EUIPO — OAuth2 client-credentials)
 # -----------------------------------------------------------------------------
-# Needed ONLY when CLEAROTRON_DATABASE=euipo (section 4). Until tracker issue 546, these were read by a side
+# Needed ONLY when CLEAROTRON_DATABASE=euipo (section 4). They used to be read by a side
 # tool that attached to every register stage whether or not they were set — so an instance with no
 # EUIPO key looked identical to one with a key. EUIPO is a register provider now: unset credentials
 # make a run REFUSE at preflight, by name, before any model spend.
@@ -342,7 +342,7 @@ EUIPO_ENVIRONMENT=production
 PROFILE_REPO_ROOT=
 SIGNA_FIXTURES_DIR=             # canned signa payloads — the $0 seam for that adapter
 
-# ── Names the audit could not see until tracker issue 1460 ───────────────────────────────────────
+# ── Names the audit could not see until the catalogue widened ────────────────────────────────────
 # Each of these is read through a name held in a string constant — `const IDENT = "NAME"` in one file,
 # `process.env[IDENT]` in another. Both halves are literals at the author's keyboard, so they were
 # always governed names; the scanner simply could not reach them. They are catalogued here now.
@@ -356,7 +356,7 @@ SIGNA_FIXTURES_DIR=             # canned signa payloads — the $0 seam for that
 # sets one. This name has no default — unset, the lane refuses. Moving it there would spend that
 # header's credibility, which every other row in that file depends on, to buy a tidier taxonomy.
 # `.env.example` promises "what you decide at install", and a must-set variable fits deciding-at-install
-# better than it fits never-set-one. Owner ruling, 2026-08-30, on tracker issue 1838.
+# better than it fits never-set-one. Ruling, 2026-08-30.
 #
 # GIVING THE LANE A DEFAULT WAS CONSIDERED AND REFUSED: refuse-by-name-when-unset is the honest design —
 # the same family as the pool root, where an unset value THROWS rather than quietly resolving somewhere
@@ -368,7 +368,7 @@ CLEAROTRON_JX_SUBCLASS_DB=
 # box's ledger and never inherits it. Sits BELOW an explicitly-named ledger file: a test that names its
 # own path is being deliberate, and this exists for the runs that name nothing.
 #
-# CANNOT LEAVE THIS FILE WHILE PRODUCT CODE READS IT (tracker issue 1838). The catalogue ratchet
+# CANNOT LEAVE THIS FILE WHILE PRODUCT CODE READS IT. The catalogue ratchet
 # refuses any product-read name with no row, and the backlog it would otherwise join turns ONE WAY.
 # So the remedy is the knobs step, not the surface step: remove the READ, not the row. A fixture
 # seam reached through the environment is that argument in its purest form.
@@ -385,7 +385,6 @@ CLEAROTRON_SUITE_TELEMETRY_DIR=
 # listed here because the catalogue ratchet is about what an operator can FIND, not what they should set.
 # Replaces PORTAL_DEMO, which named only one of the processes that has to know.
 # Read by driver/portal-service.mjs, driver/demo-posture.mjs and mcp-server/http-server.mjs.
-# Refs tracker issue 2015, 2106.
 # effect: deployment
 CLEAROTRON_DEMO=
 
@@ -400,7 +399,7 @@ CLEAROTRON_DEMO=
 # IT IS NOT A RUN-SLOT, deliberately. A what-if that took a slot from CLEAROTRON_MAX_CONCURRENT_RUNS could
 # BLOCK an admitted paid run rather than merely share the machine with it — the same starvation one
 # layer up. So the two pools are separate and only this one bounds experiments.
-# Read by driver/whatif-worker.mjs. Refs tracker issue 1953.
+# Read by driver/whatif-worker.mjs.
 # effect: tuning
 CLEAROTRON_WHATIF_MAX_CONCURRENT=1
 
@@ -421,7 +420,7 @@ CLEAROTRON_WHATIF_MAX_CONCURRENT=1
 #
 # Surfaced by the cut-over overlay control once the withheld `ops/` bucket was laid back over the public
 # tree: the ratchets that would have caught it had had no subject since the cut, so this is a gap of
-# long standing rather than a regression. Refs tracker issue 213.
+# long standing rather than a regression.
 #
 # Left EMPTY here on purpose. A path in this file would read as a default; there is none, and the
 # installer supplies the real value.
@@ -438,7 +437,7 @@ CLEAROTRON_CHECKOUT_DIR=
 # GitHub sets GITHUB_*, so a row would document somebody else's decision. We set these, so a row
 # documents ours.
 #
-# Found by the audit while closing tracker issue 213, not by that issue's diagnosis — they arrived with
+# Found by the audit rather than by the diagnosis that prompted it — they arrived with
 # tonight's release-pipeline work and the catalogue ratchet caught them on the next run, which is the
 # ratchet doing its job. Raised with the release lane rather than silently absorbed.
 
@@ -446,7 +445,12 @@ CLEAROTRON_CHECKOUT_DIR=
 # checkout may have moved on since, and a decision made about "whatever HEAD is now" tried to republish
 # an already-released version. Unset falls back to HEAD, which is correct for the cron and for a hand
 # run, where nothing has moved. Read by scripts/release-cut-decision.mjs.
-# effect: deployment
+#
+# DECLARED `deployment` FIRST, AND THAT WAS THE WRONG HALF OF THE DEFINITION. `deployment` is "where
+# input and output live" — a pool root, an outbox, a database path. A git ref is not a location any
+# input or output lives at; it is which subject the decision is taken about, and it changes only whether
+# the pipeline republishes something it already shipped. Nothing a clearance run produces moves.
+# effect: tuning
 CLEAROTRON_CUT_REF=
 
 # How long publishing waits for a parked version run, in whole milliseconds. Unset uses the built-in
@@ -455,3 +459,90 @@ CLEAROTRON_CUT_REF=
 # entirely, which is that script not running at all. Read by scripts/release-await-cut.mjs.
 # effect: tuning
 CLEAROTRON_RELEASE_WAIT_MS=
+
+# ── The local key door's socket ───────────────────────────────
+# Same shape as the two below: read by product code, in neither this file nor the governance table
+# until a private environment-contract ratchet caught it.
+
+# WHERE the local key door listens. Unset means there is no key door and a deployment gets exactly the
+# door it had before — this adds a path, it does not widen the existing one.
+#
+# WHY A SOCKET AND NOT A PORT. This interface serves two populations that authenticate differently:
+# people arriving through a tunnel, who prove themselves with a proxy identity, and programs on the same
+# machine holding a scoped access key, which can never produce one. "Only accept a key from loopback"
+# does not separate them — the tunnel daemon runs on the same machine, so a request forwarded from the
+# internet and one from the local portal arrive with the same peer address. A tunnel forwards to a port;
+# it cannot reach a socket, so the transport is the discriminator.
+#
+# The socket is created 0660, owner and group only, and the mode is set after listen because listen
+# creates the file and the umask decides what it starts as. The door refuses to open at all without a
+# grants file, alongside the authentication bypass, or in token mode — that mode makes the NETWORK door
+# take a key too, which is the thing this exists to prevent.
+#
+# Read by mcp-server/key-socket.mjs.
+# effect: deployment
+TRADEMARK_MCP_KEY_SOCKET=
+
+# ── Who the completion notice reaches ────────────────────────────────────────────────────────────
+# Both arrived together and shipped undeclared: they are read by product code and were in
+# neither this file nor the governance table, which six private environment-contract ratchets caught on
+# the next overlay run. Catalogued here on the same terms as the release names above — they are OUR
+# names, read by code that ships.
+
+# WHO the chat notice is addressed to: a JSON object of requester email or handle → number, e.g.
+# {"lisa@tenant.example":"+41...","jordan":"+41..."}. Before this, the notice went to a map keyed by
+# AGENT id, and every user of a deployment shares one agent — so the operator was notified about work
+# other people ordered and the requester was told nothing.
+#
+# UNSET IS AN EMPTY ROSTER, never a demo one. A deployment that configures nothing routes no notice and
+# the delivery record says whose number is missing, by name. The sibling agent map carries invented
+# numbers for offline tests; doing that here would aim a real client's completion notice at a fixture.
+#
+# It holds contact data. Read by driver/stages.mjs (whatsappRouting).
+# effect: deployment
+CLEAROTRON_REQUESTER_WHATSAPP=
+
+# The operator's own copy of the same notice, ON unless this is `0`, `false` or `no`. Independent of the
+# roster above: an operator can stop receiving copies of everyone else's runs without touching who the
+# requester notice reaches. Read by driver/stages.mjs (whatsappRouting).
+# effect: deployment
+CLEAROTRON_WHATSAPP_OPERATOR_COPY=
+
+# ── The two switches that reveal accounts an install deliberately does not offer ──────────────────
+#
+# NEITHER IS FOR AN OPERATOR. Both are set by the product's own commands, and a row here exists because
+# product code reads them, not because copying this file should set them. Leave both unset. Setting
+# either on a real deployment puts accounts in a picker that a clean install is meant not to have.
+#
+# `1` makes the profile loader return the three test-suite fixture accounts in the roster
+# it resolves. They are marked `testFixture` and are refused otherwise on every install route, because a
+# packaging exclusion protects only the tarball and `git clone && npm install` is a documented way in.
+# Set by scripts/test-run.mjs, once, for every child — most checks that need a fixture do not call the
+# loader directly, so there is no argument to pass. An explicit `includeTestFixtures` argument beats
+# this, distinguished on `undefined`, so a check asking what a customer's install resolves is never
+# handed the suite's answer instead. Read by driver/profiles.mjs.
+# effect: harness
+CLEAROTRON_TEST_FIXTURE_PROFILES=
+
+# `1` makes the profile loader return the BUNDLED demo account (demo-brand-owner, marked `demoData`).
+# A fresh install resolves `generic` alone — ruling 2026-09-08, so nobody has to clean demo
+# material out of an environment they just made — and the demo brings its own account when it runs.
+# Set by `clearotron demo`, by `clearotron start --demo`, and by scripts/test-run.mjs.
+#
+# The gate is on the LAYER, not the flag: a `demoData` account in a deployment's OWN configured store is
+# that deployment's choice and stays offered whatever this is set to, and the admission wall still
+# refuses a real clearance under it. An explicit `includeDemo` argument beats this, on the same rule.
+# Read by driver/profiles.mjs.
+# effect: harness
+CLEAROTRON_DEMO_PROFILES=
+
+# ── The organisation setup names ──────────────────────────────────────────────────────────────────
+#
+# Your organisation's name. `npm run setup` asks for it directly after the sign-in address and writes it
+# here, quoted, so a name holding a `#` survives. 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 or empty, no
+# organisation is invented. `clearotron start --organisation <name>` supplies it for one start, and a
+# demo never reads it. Read by bin/start.mjs.
+# effect: deployment
+CLEAROTRON_ORGANISATION_NAME=

package/.nvmrc

@@ -1 +1 @@
-22
+22.13

package/CONTRIBUTING.md

@@ -6,6 +6,10 @@ you cannot run and why, and the three rules that fail CI if you miss them.
 Start with [README.md](README.md) for what the engine does and [INSTALL.md](INSTALL.md) for a real
 installation.
 
+If a word in the code means something you did not expect, [`docs/GLOSSARY.md`](docs/GLOSSARY.md)
+defines the ones that carry a local meaning — arm, seat, plant, ledger, receipt, carry-through and
+the rest — with the file that owns each.
+
 ## What you can run, with nothing but a clone
 
 **Node 22 is a hard floor.** `package.json` declares it, `.nvmrc` pins it, and the free US register
@@ -76,7 +80,7 @@ product and will not be published. Its absence weakens nothing you can run — t
 the machinery, and the scenario suite covers the answers. The validation ladder, from the $0 offline
 suite to a paid live run, is [docs/E2E.md](docs/E2E.md).
 
-**Some comments cite issues you cannot open** — `(tracker issue 324)` and the like, against the private tracker this
+**Some comments cite issues you cannot open** — `` and the like, against the private tracker this
 repository was cut from. They are being removed rather than preserved.
 [ADR-0005](docs/decisions/0005-comments-carry-reasoning.md) is the ruling and states what a new comment
 has to meet; read it there rather than from a summary here. New work cites this repository's issues
@@ -91,13 +95,13 @@ any writing pass over the documentation, applies to them.
 
 ## The three rules that fail CI
 
-**1. Rebuild `portal-ui/dist` and commit it.** The bundle is committed so a deploy never builds. CI
-rebuilds it from source and requires byte equality, so a change under `portal-ui/src` that ships
-without its rebuilt bundle fails:
+**1. Build `portal-ui/dist` before you push.** The bundle is not committed; it is gitignored, and
+CI runs `npm run build:ui` from source. So there is nothing to add — run it locally when you touch
+`portal-ui/src`, because a bundle that does not build fails CI and there is no committed copy to
+fall back on:
 
 ```bash
 npm run build:ui
-git add portal-ui/dist
 ```
 
 CI builds on the exact Node version named in