clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/.env.example

@@ -1,7 +1,7 @@
 # =============================================================================
 # example.com-trademark — canonical environment contract (.env.example)
 # =============================================================================
-# The prelim-search product reads all of its configuration + credentials from
+# The clearance-search product reads all of its configuration + credentials from
 # the environment. In production these live in the systemd EnvironmentFile
 # (`~/.env`, loaded as whichever service account runs the engine); in dev they are
 # exported before the run. This file is the DOCUMENTED CONTRACT — copy it to
@@ -49,8 +49,6 @@
 #     product code that declares nothing; 96 existing names are a frozen backlog, not a pass. The
 #     declaration records what a class IS, and is not a claim that it is harmless — the guard checks
 #     the string, a reader checks the truth.
-#   • "Reconstructed" / "verify at deploy" notes flag values that could not be
-#     confirmed inside this repo (see AZURE_OPENAI_* below).
 # =============================================================================
 
 
@@ -79,12 +77,16 @@
 # 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
-# register credential below, and no register source removes it.
+# Either way the reasoning is paid for on its own: a subscription, an API key, or (Claude only) your own cloud
+# account, chosen by CLEAROTRON_AI_BILLING below. That is separate from every register credential below, and
+# no register source removes it.
 CLEAROTRON_AI=anthropic-agent
-# Path/name of the engine binary — ONE PER ENGINE. Only the live engine's value is read, so a box that
-# runs one engine sets one and a box that runs both sets both, to different paths. Give each an ABSOLUTE
-# path if the binary is not on PATH: stage subprocesses run with cwd set to the run directory.
+# Path/name of the engine binary — ONE PER ENGINE, and only to force one copy. Left as the engine's own
+# word (`claude`, `codex`) or unset, a run takes the program on PATH, then the copy setup installed. Do not
+# write the path of setup's copy here: it would become the forced copy, and one installed later would never
+# be used. A path set here must be ABSOLUTE: stage subprocesses run with cwd set to the run directory.
+# Only the live engine's value is read, so a machine that runs both engines can set both.
+# effect: setup
 CLEAROTRON_CLAUDE_PATH=claude
 
 # ── openai-agent (codex) knobs — ONLY read when CLEAROTRON_AI=openai-agent ────────────────────────
@@ -92,7 +94,9 @@ CLEAROTRON_CLAUDE_PATH=claude
 # overwriting the other — these were one variable until that collapse met a box needing two different
 # paths, and this file shipped two live rows for the single name until then (a last-wins assignment in
 # the copied `.env`, not a choice).
+# effect: setup
 CLEAROTRON_CODEX_PATH=codex
+
 CLEAROTRON_WORK_DIR=
 # Customer/project config store (loadProfiles). Unset ⇒ driver's built-in profiles dir.
 CLEAROTRON_CUSTOMERS_DIR=
@@ -102,15 +106,28 @@ CLEAROTRON_INSTRUCTIONS_DIR=
 # 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,
+# Run-slot lock dir. Default = $CLEAROTRON_WORK_DIR/clearance-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; 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.
+# Delivery outbox dir (instant handoff-mode delivery wake). Default = $CLEAROTRON_WORK_DIR/clearance-outbox.
+# Was `prelim-outbox`. A box that never set this keeps its markers there and they are still read and drained;
+# new markers are written under the new name. Nothing to move.
 # effect: deployment
 CLEAROTRON_OUTBOX_DIR=
+# Where the shared register CALL ledger lives — the per-query record the register spend is counted from.
+# Default = ~/trademark/telemetry/register-calls.jsonl. An install that moves or clears it changes what a
+# later cost read can account for, and nothing else records where it went.
+# effect: deployment
+CLEAROTRON_REGISTER_CALL_LOG=
+# Where the register RECORD log lives — the fetched-record store a "verified from the record" claim on a
+# report joins against. Resolved by EXISTENCE over several directories and filenames, not by name alone,
+# so that an install which inherited an older path keeps reading its own ledger; setting this overrides
+# that ladder outright. An install pointed at an empty path reports no fetched records and no fault.
+# effect: deployment
+CLEAROTRON_REGISTER_RECORD_LOG=
 # 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=
@@ -181,19 +198,20 @@ CLEAROTRON_DATABASE=clarivate
 
 
 # -----------------------------------------------------------------------------
-# 2. MODEL / API CREDS  (Anthropic subscription/API + the Azure catalog id)
+# 2. MODEL / API CREDS  (a subscription, an API key, or your own cloud account)
 # -----------------------------------------------------------------------------
 # Anthropic API key. NOTE: the anthropic-agent engine STRIPS this from the `claude -p`
-# 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).
+# subprocess unless CLEAROTRON_AI_BILLING=api-key, so the subscription or your cloud account pays, not
+# the API. A gateway's credential is ANTHROPIC_AUTH_TOKEN (below).
 ANTHROPIC_API_KEY=sk-ant-...
 # 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
+# untouched in every billing mode (spawnEnv strips only the API key), so this row is the whole
 # mechanism by which a browserless server authenticates the subscription lane.
 # external: read by the claude CLI itself, not by this product's code — inheritance is the contract
 CLAUDE_CODE_OAUTH_TOKEN=
-# Auth mode for the engine: "subscription" (default) or "api-key". It applies to WHICHEVER engine
+# Auth mode for the engine: "subscription" (default), "api-key", or "cloud" for Claude through your own
+# cloud account (the block below this setting). It applies to WHICHEVER engine
 # CLEAROTRON_AI names, and each engine reads a DIFFERENT key under "api-key" — this is the pairing to
 # get right, because the wrong one is refused at the run door rather than at setup:
 #
@@ -204,6 +222,16 @@ CLAUDE_CODE_OAUTH_TOKEN=
 # `npm run setup` asks this as its own question, adopts the key, and proves the pair with one cheap
 # turn before writing anything — so a hand-edit here is the second-best route.
 CLEAROTRON_AI_BILLING=subscription
+# CLAUDE THROUGH YOUR OWN CLOUD ACCOUNT: CLEAROTRON_AI_BILLING=cloud, anthropic-agent only. The Claude
+# program reads those names itself; Clearotron has none of its own there. A search is refused unless
+# exactly one cloud is switched on or a gateway URL alone is named, and refused with a switch left on
+# under subscription or api-key. Every run records which cloud paid.
+#
+# The settings themselves are not listed here, because this file is the short one a reader meets first
+# and the cloud rows are sixteen of them. INSTALL.md §3b walks the three clouds and the gateway, and the
+# configuration reference's credentials table gives every name with what reads it. `npm run setup` asks
+# for the same things and proves them with one turn, which is the route to prefer either way.
+#
 # 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
 # refuses before spending if it is absent, so subscription is not the precondition-free option there.
@@ -214,17 +242,6 @@ CODEX_API_KEY=
 # set needs to know it is removed, not because setting it here does anything: it never serves as the
 # api-key credential — CODEX_API_KEY does.
 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.
-# 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.
-# 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
-AZURE_OPENAI_API_VERSION=2024-10-21
 
 
 # -----------------------------------------------------------------------------
@@ -480,6 +497,21 @@ CLEAROTRON_CUT_REF=
 # effect: tuning
 CLEAROTRON_RELEASE_WAIT_MS=
 
+# Whether this release run was dispatched to cut. The workflow sets `true` on a `workflow_dispatch` that
+# is not a rehearsal, and `false` otherwise. Set, a wait that expires with no version published is a
+# failure that names why, because the one thing the run was dispatched for did not happen; a push or the
+# schedule asks nothing of the wait, so expiry there stays a quiet success. Read by
+# scripts/release-await-cut.mjs.
+# effect: tuning
+CLEAROTRON_CUT_REQUESTED=
+
+# The number of the version pull request the same run opened, so a failed wait reads why that pull
+# request did not merge rather than guessing. The workflow sets it from the version job's output. Unset,
+# or not a whole number, a dispatched wait says it found no pull request to wait on. Read by
+# scripts/release-await-cut.mjs.
+# effect: tuning
+CLEAROTRON_CUT_PR=
+
 # A GitHub token carrying Actions read and write. The release workflow supplies it from a repository
 # secret so that a cut does not wait for a person to approve the version pull request's parked CI run:
 # that run is authored by the repository's own Actions bot, and GitHub parks bot-authored runs as

package/CONTRIBUTING.md

@@ -54,7 +54,7 @@ Four more things run for free:
 | Command | What it proves |
 |---|---|
 | `node mcp-server/smoke.mjs` | Drives the real MCP server over stdio against a built fixture. Prints `SMOKE OK`. |
-| `node driver/dev-portal.mjs` | Serves a pool at `http://127.0.0.1:18899/` — archive index, reports, customer pages. Loopback only; it refuses any other host. Needs a pool to point at (`CLEAROTRON_REPORTS_DIR`). |
+| `node driver/dev-portal.mjs` | Serves a pool at `http://127.0.0.1:18899/` — archive index, reports, company pages. Loopback only; it refuses any other host. Needs a pool to point at (`CLEAROTRON_REPORTS_DIR`). |
 | The $0 mock pipeline | A full run — intake, every stage, publish, delivery packet — on a mocked engine. Recipe in [docs/E2E.md § Tier 1](docs/E2E.md). Follow it as written; the absolute-path trap in it catches everybody. |
 | `npx clearotron demo` | Replays `demo/` — a real run on a fictional mark — through the real publisher into `~/trademark-demo/pool` and serves it. No keys, no model, no engine. |
 
@@ -75,7 +75,7 @@ half did not run. `npx clearotron install` walks through both, and
 [INSTALL.md § 1](INSTALL.md#1-prerequisites) is the full list.
 
 **The scenario suite is private by design.** `scripts/e2e.mjs` scores runs against lawyer-written
-reference answers on real matters; the references and the config store they load from are client work
+reference answers on real matters; the references and the config store they load from are company work
 product and will not be published. Its absence weakens nothing you can run — the in-repo suite covers
 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).
@@ -130,13 +130,13 @@ The reviewer is the check. Say what you checked in the PR rather than citing a p
 **3. Types are enforced, and `vite build` does not typecheck.** `npm run typecheck -w portal-ui`
 runs as its own CI step. Run it before you push.
 
-**4. Every sentence a customer reads is written against the standard, and five classes of it are
+**4. Every sentence a company reads is written against the standard, and five classes of it are
 checked.** The standard is [`docs/writing-standard.md`](docs/writing-standard.md); the prose rules
 under it are [`docs/writing-rules.md`](docs/writing-rules.md), and they apply first. Together they
 bind report HTML, portal screens, the README and the docs.
 
 `node scripts/writing-standard-check.mjs` refuses what your change ADDS to one of those surfaces:
-an engineering identifier in text a client reads, a reviewer-only marker in rendered output, a known
+an engineering identifier in text a company reads, a reviewer-only marker in rendered output, a known
 caveat sentence, a screen that writes its own page heading instead of using `PageHeader`, and a lede
 whose words are all already in its title. It names the class and prints the line. It never rewrites —
 a rewritten sentence is a sentence nobody reviewed.
@@ -153,7 +153,7 @@ identifier, no caveat and no banned word and still be the thing the standard exi
 heading that restates its section, a paragraph explaining what the reader can already see, a sentence
 that only works if you know how the engine is built.
 
-So: **a pull request that changes text a customer reads is reviewed against the rendered page or
+So: **a pull request that changes text a company reads is reviewed against the rendered page or
 report, not against the diff.** One reviewer reads it as someone who has never seen this product and
 asks one question of every new sentence — *what would a reader with zero context think this means?*
 If the answer needs the codebase, the sentence is cut or rewritten. One reviewer, one question,
@@ -288,9 +288,9 @@ narrower is usually the defect rather than the fix, and it will be read that way
 
 ### The three possible outcomes
 
-**Into the base layer.** Your change becomes part of what every install gets, including ours and our
-clients'. That is the highest bar: it has to be an improvement for the matters this doctrine is tuned
-for, not only for yours.
+**Into the base layer.** Your change becomes part of what every install gets, including ours and the
+installs we run for companies. That is the highest bar: it has to be an improvement for the matters
+this doctrine is tuned for, not only for yours.
 
 **Published as a pack.** Doctrine resolves file by file — an install can point at another directory and
 have its files win, with everything it does not override falling through to ours. So a change that is