clearotron 0.2.3 → 0.2.4

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. Owner 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.
 
@@ -485,7 +484,7 @@ CLEAROTRON_RELEASE_WAIT_MS=
 TRADEMARK_MCP_KEY_SOCKET=
 
 # ── Who the completion notice reaches ────────────────────────────────────────────────────────────
-# Both arrived with tracker issue 289 and shipped undeclared: they are read by product code and were in
+# 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.

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
@@ -91,13 +95,13 @@ any writing pass over the documentation, applies to them.
 
 ## The three rules that fail CI
 
-**1. Rebuild `portal-ui/dist` before you push.** The bundle is not committed — CI builds it from
-source and requires byte equality, so a change under `portal-ui/src` that does not build cleanly
-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

package/INSTALL.md

@@ -1,4 +1,6 @@
-# Install & Operate
+# Install & Operate — the reference
+
+[QUICKSTART.md](QUICKSTART.md) gets one search running in three commands. This is everything else.
 
 Two documents in one file, and most readers need only the first. The engine needs no agent gateway — the
 reasoning stages' only external LLM dependency is a coding CLI: the Claude CLI (the default) or the codex
@@ -46,9 +48,22 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
 - **macOS, Linux, or native Windows for the demo; WSL2 for a clearance.** `npx clearotron
   demo` runs anywhere Node does, native Windows included. A real clearance does not: the engine resolves
   the reasoning CLI the POSIX way, so a native-Windows clearance refuses at preflight even with the CLI
-  on `PATH`. On Windows, `wsl --install`, then install Node 22.13 or newer **inside** the Linux distribution and work
-  through this page from there. A *hosted*
-  deployment needs Linux for one further thing, the systemd outbox trigger —
+  on `PATH`. On Windows, `wsl --install -d Ubuntu`, then `wsl -d Ubuntu`, and work through this page
+  from **inside** that distribution. Name it: plain `wsl` can open a minimal image with no apt, no
+  curl and no bash, and everything below assumes Ubuntu. A fresh Ubuntu has no Node at all, and
+  apt's package is below the floor above, so `npx` answers "not found" before anything of ours runs.
+  From the Ubuntu prompt:
+
+  ```bash
+  sudo apt update && sudo apt install -y curl
+  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+  . "$HOME/.nvm/nvm.sh" && nvm install 22    # 22.13 or newer, per the floor above
+  npm install -g @anthropic-ai/claude-code
+  claude                              # once, interactively, to sign in
+  npx clearotron install
+  ```
+
+  A *hosted* deployment needs Linux for one further thing, the systemd outbox trigger —
   [driver/systemd/README.md](driver/systemd/README.md).
 - **A reasoning CLI on your `PATH`, signed in.** This is the prerequisite people miss. Every stage runs
   as a headless turn of a third-party binary, and `CLEAROTRON_AI` picks which one for the whole install.
@@ -151,6 +166,11 @@ you want the second one** — the first assumes access to the repository, which
 
 ### From the repository
 
+**This is the development tree, and it is for contributors.** If you want to run a clearance, take one
+of the two routes above instead. A clone is not a smaller version of the package — it carries the
+fixtures and sample brand owners the project develops against, and those load as real records. They
+are not yours and they are not in the package, which excludes them deliberately.
+
 ```
 git clone <this-repo> && cd <repo>
 npm install            # installs all workspaces

package/README.md

@@ -15,7 +15,7 @@ web for conflicts, reasons about the risk the way a clearance lawyer would, and
 report with a machine-readable audit trail behind every finding. It runs headless on your own machine:
 no gateway, no platform, and nothing about your matters reaches us.
 
-[Install & operate](INSTALL.md) · [Docs](docs/README.md) · [Security](docs/SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Licence](#licence)
+[Quickstart](QUICKSTART.md) · [Install & operate](INSTALL.md) · [Docs](docs/README.md) · [Security](docs/SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Licence](#licence)
 
 ## Install
 
@@ -71,7 +71,7 @@ sentence, or set the classes, marketplaces and search depth yourself:
 ![The new-clearance screen — classes, marketplaces and the four search depths](docs/assets/portal-new-clearance.png)
 
 A finished clearance reads like this — the verdict, the risk band and the four answers. **The mark
-VENQORI is invented; the EUIPO register data behind it is real and live**, and the report says so on
+VENQORI is invented; the register data behind it is real and live**, and the report says so on
 its own face:
 
 ![A finished clearance report — the verdict, the risk band and the four answers](docs/assets/portal-clearance-report.jpg)
@@ -90,7 +90,7 @@ npx clearotron run --job my-job.json
 
 ## How it fits together
 
-- **A reasoning CLI does the thinking.** Every stage runs as a headless turn of the [Claude CLI](https://claude.com/claude-code) (`claude`) or the Codex CLI (`codex`), installed and signed in. An `ANTHROPIC_API_KEY` is not a substitute: the key decides what the child process is handed, not whether one is spawned.
+- **A reasoning CLI does the thinking.** Every stage runs as a headless turn of the [Claude CLI](https://claude.com/claude-code) (`claude`) or the Codex CLI (`codex`), which must be installed. `CLEAROTRON_AI_BILLING` chooses what pays for the turn: your signed-in subscription, or an API key. Either way the CLI is what runs — there is no path that calls the model directly.
 - **One register credential sets coverage and cost.** `CLEAROTRON_DATABASE` has no default — a run refuses rather than picking a vendor for you. EUIPO and a local USPTO index cost nothing; Signa, Clarivate and Corsearch are subscriptions. [The six, and what each reaches](providers/README.md).
 - **One research key.** `PERPLEXITY_API_KEY` covers the open web and the marketplaces. A clearance refuses without it at the door, before a register stage has spent.
 - **A run takes hours, and survives interruption.** Every finished stage stays on disk; a resume re-runs only what is missing, and a run parked on a provider cap continues by itself.
@@ -115,7 +115,8 @@ credential.
 
 | Goal | Start here |
 |---|---|
-| Install, configure and operate it | [INSTALL.md](INSTALL.md) |
+| Get one search running | [QUICKSTART.md](QUICKSTART.md) |
+| Install, configure and operate it | [INSTALL.md](INSTALL.md) — the reference |
 | Pick a register, or run without a paid vendor | [INSTALL.md § 3a](INSTALL.md#3a-running-without-a-paid-register-vendor) |
 | Submit jobs, or consume what a run emits | [INTAKE](docs/INTAKE.md) · [DELIVERY](docs/DELIVERY.md) |
 | Read and question a finished run from a chat app | [mcp-server/CONNECT.md](mcp-server/CONNECT.md) |
@@ -128,8 +129,8 @@ credential.
 A clone is the working tree, not a way to install the product — install it from the package above.
 
 ```bash
-git clone https://github.com/CordilleraSarl/Clearotron
-cd Clearotron
+git clone https://github.com/CordilleraSarl/clearotron
+cd clearotron
 npm install                    # every workspace
 npm run build -w portal-ui     # the browser bundle is not committed — build it once
 npm test                       # the offline suite — no credentials, no network

package/bin/example.mjs

@@ -6,7 +6,7 @@
 //   npx clearotron demo                    replay demo into ~/trademark-demo and open the portal
 //   npx clearotron demo --product <id>     replay a different product's demo (the ids are listed below)
 //   npx clearotron demo --run-dir <dir>    replay a frozen example from somewhere else
-//   npx clearotron demo --base <dir>       put the whole demo somewhere else (remove it with one rm -rf)
+//   npx clearotron demo --base <dir>       put the whole demo somewhere else (one directory to remove later)
 //   npx clearotron demo --port 9000        serve on another port (the demo opens three doors:
 //                                          9000, 9001 and 9002)
 //   npx clearotron demo --no-open          do not try to open a browser
@@ -39,6 +39,7 @@ import "../shared/env-local.mjs";   // step 4 / — FIRST: this program read a
 // back-filled. Placed above every other import because a side-effecting import runs in order.
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
+import { removeDirectory } from "../shared/os-advice.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — the printed command is resolved once, for the reader who is actually standing there
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -257,8 +258,8 @@ const published = results[0].published;
 
 // THE LABEL. The reader is about to look at a document that reads like advice about a real mark. It is
 // not, and the demo says so before the browser opens rather than in a footnote nobody reaches.
-console.log("  Real engine output for the fictional mark VENQORI — captured 2026-08-11 against the");
-console.log("  production EU register, replayed locally: no keys, no model calls, no register queried.");
+console.log("  Real engine output for the fictional mark VENQORI, captured against Clarivate Compumark.");
+console.log("  Replaying it needs no account, no key and no network.");
 console.log("  Every number, band and citation below was produced by that real run and is being");
 console.log("  re-rendered from its artifacts. It is an example, not advice.\n");
 // NAMES THE POPULATION. This printed "13 finding(s)" beside a report showing
@@ -315,7 +316,7 @@ if (has("--once")) {
   // the base there would tell a reader to remove a directory that does not exist and leave the one that
   // does — worse than silence, because it reads as an answer.
   const created = flag("--pool") ? poolRoot : demoBase;
-  console.log(`  Removing it later is one directory:  rm -rf ${created}\n`);
+  console.log(`  Removing it later is one directory:  ${removeDirectory(created)}\n`);
   // NOT A BARE ZERO. A demo that failed to replay one of its four sets `exitCode` above, and exiting 0
   // here would discard it — printing the failure and then reporting success, which is the shape this
   // change exists to remove. `--once` is also the invocation a script is most likely to use, so it is
@@ -364,7 +365,7 @@ const startArgs = ["--demo", "--base", demoBase];
 if (flag("--port")) startArgs.push("--port", flag("--port"));
 if (has("--no-open")) startArgs.push("--no-open");
 
-console.log(`  Removing this demo later is one directory:  rm -rf ${demoBase}`);
+console.log(`  Removing this demo later is one directory:  ${removeDirectory(demoBase)}`);
 strayFromAnOlderDemo();
 console.log("");