io.github.CordilleraSarl/clearotron

OPS-ONLY. Consume ONE routed outbox event by its file name (from list_outbox_events). Idempotent (ok+alreadyGone). The delivered marker is instead cleared by mark_sent.

START HERE for any 'what do you have on X / what did the search find' question — ONE plain-language briefing of a run, in the client-voiced wording (which search product this run was, overall risk in plain words, each conflict in 1–2 plain sentences, any conditions on the result). Facts, never advice. No internal stage names, no risk-formula codes, no model names. Reach for the audit tools (get_run, trace, decision_timeline, get_telemetry) only when the user asks HOW the system reached a conclusion.

ENGINEERING/AUDIT view — the run's DECISION timeline: an ordered milestone list projected from the event log — stages (with trigger and a 'changedFromPrevious' marker when a stage was recomputed), skeptic escalations (with the reason), the verdict(s) (with the reviewer's head note), screen-gates, and the terminal outcome. Answers 'how did the verdict evolve?' in one call; for 'what did it find', call brief instead.

START HERE before composing a search — the option space, for free. Returns the four searches this deployment can actually run — each with the geography it accepts, how many names it reads, its turnaround, whether it carries the case-law reading, whether the native-language investigation is optional or automatic, and a plain note when one is unavailable — plus the combination rules the servers enforce (territories, native-language routing, marketplaces, classes, names per search), and — for a client connector — YOUR OWN account: its key (the profileKey plan_run and start_run require), its projects, its saved searches (the recipeKey slugs) and what is left of today's allowance. Omit profileKey to be answered about your own account(s); pass it to ask about a specific one. Reserves nothing, spends nothing, starts nothing. Then: plan_run (free) with the arguments you intend, and start_run with the SAME arguments once the requester has confirmed.

Diff two versions of an artifact (what actually changed between them). Versions exist only when something snapshotted them — an in-place re-dispatch (_history) or a what-if experiment (_experiments); the automated escalation/correction overwrites in place, so a normal run has only 'canonical' and there's nothing to diff (reported honestly). Defaults: a=canonical, b=newest snapshot.

OPS-ONLY. Late-bind context onto a run: the applicant + exclusions (written as customer-bind.json, the pipeline's pre-start applicant bind). Use to resolve a customer-unknown run.

What was searched vs what's a gap: per-register-axis presence/validity, the coverage-ledger marker, negative-results count, and per-artifact validity.

The run's send payload: _driver/delivery.json (subject, recipient routing, verbatim emailBodyHtml, whatsapp line) and/or failure.json, plus sendPending/.sent state. NOT exposed to client tokens.

One finding/negative/audit-trail record by id (F#, NR#, AT#).

ENGINEERING/AUDIT view — billed register-search provider call counts for the run, RECOMPUTED live from the ledger (more correct than the cached value) with a drift/low-confidence flag.

ENGINEERING/AUDIT view — full run mechanics: status, every pipeline stage (trigger/outcome), failover facts, artifact validity, and a coverage summary. Use when the user asks how the run executed; for 'what did it find', call brief instead.

What the search covered and what is still open, in the report's own words — each area with its state (Searched — clean / Partially covered / Open item / Not run this run). An area that is not clean is NOT cleared: read it as open. Reach for this whenever a result looks clean and the user is about to rely on it.

ENGINEERING/AUDIT view — per-run + per-stage execution telemetry (models, tokens, wall, failovers, fail reasons) from run.jsonl + the per-attempt logs. The ONLY tool that reports model identity — keep model names out of answers unless explicitly asked. Pass stage (+axis) to focus.

The records this search considered — every register and common-law entry, including ones the report does not name individually. Each carries the mark, owner and country, the classes, the register status, the source link, whether the provider record was actually retrieved (`retrieved`), and `superseded: true` if a later pass withdrew it. Use this to answer 'what exactly did you find, and who owns it?'. Filter with layer: register | common-law.

Structured findings from the deterministic audit. kind: findings (default) | negatives | audit (audit-trail). Filter by sourceLayer (Register/Common-law). Pass group (on-field/off-field/out-of-scope) to get the curated report cards instead — the cards' one-liners are already plain-language.

Integrator discovery read (docs/DELIVERY.md): every pending outbox event — delivered markers plus the self-contained run-failed / intake-rejected / duplicate-skipped / late-bind-ack packets. Route each, then mark_sent (delivered) or ack_event (the rest).

List the customer ACCOUNTS the firm runs clearotron clearances for (key + name + industry + their PROJECTS) — the roster the intake step resolves a job's profileKey (and optional projectKey) against. profileKey selects that customer's marketplaces, default classes/jurisdictions, report format and risk posture; a project (spec 62) is an engagement UNDER a customer that overlays its own marketplaces/classes/sector/posture. Resolve by JUDGMENT (explicit name, misspelling, or implicit reference); OMIT profileKey for a new/unknown customer (uses the neutral generic profile — a customer who does not exist here yet never blocks a search; tell the requester it is running under the neutral profile, and that their own company can be set up in the portal if they want its framework, territories and marketplaces applied instead); set projectKey only when the request names a specific project in that customer's projects[], else OMIT it (runs on the customer profile); never pick a profile from the sender's email domain. Read-only.

List the searches this session can see (in progress and finished), newest first. A session may hold more than one client, so the list is NOT one client's: every row names the client it was run for, and the project where there is one. TO FIND ONE CLIENT'S SEARCHES, pass `mark` with the client's name — the same name-shaped filter reads the client and the project as well as the mark. TO FIND A SEARCH BY THE NAME IT CLEARED, pass `mark` — the stored identifier is a longer prefixed slug a client has never seen, so a bare mark name will not match `slug`. If a filtered call comes back empty, list unfiltered and read down the mark names before telling anyone there is nothing there. States: 'postponed' = paused on a provider cap and resuming by itself (resetsAt); 'recovering' = backing off and retrying (recoveryResumesAt); 'parked-for-human' = interrupted mid-search, resumes on the next activation. sendPending:true is the authoritative list of finished searches still owed their delivery notification. Follow up with brief for a plain-language summary of one search.

What the search looked for and where — the searches that came back empty as well as the ones that surfaced something. Each row carries the term, the match shapes tried (exact, fuzzy, phonetic, transliteration…), the classes and jurisdictions, the register office where one was named, and the outcome (no-hit | found | out-of-scope | screened-out | excluded-own-rights | negligible). This is the defensibility record: proof of where the search looked and found nothing. Filter by outcome.

OPS-ONLY. Integrator write-back after sending a delivered run's packet (docs/DELIVERY.md step 3): writes the .sent idempotency guard, clears status.sendPending, removes the outbox marker. Idempotent — an already-sent run returns ok+alreadySent. SETTLING REQUIRES EVIDENCE: pass messageId or attestation, or the call refuses. Never call this for a send that was blocked or failed — leave the marker so the send stays owed.

FREE PREVIEW — resolve what a search WOULD do and return it, spending nothing and queueing nothing. Takes the SAME arguments as start_run. Use this BEFORE start_run whenever the requester has not already confirmed the specifics: it reports the PRODUCT that resolves and WHERE it came from (their request, the account default, a saved search, or the territories themselves), the territories and marketplaces that would ACTUALLY be searched, the turnaround, and any blockers as questions to put back. Show the result to the requester; then call start_run with the SAME arguments to actually run it. Nothing here reserves or holds anything.

Read a run artifact's raw text (or one '# Section', or its front-matter). For briefing a person, the report is the plain-language layer; the rest are internal working documents. Names: report, audit, narrative, registerFindings, commonLaw, placement, matterContext, variantManifest, skepticFlags, seniorEyeReview, caseLaw, clientSummary (internal cover-note source; ops only), a register axis (e.g. primary-sweep), status.json, run.jsonl.

Change-feed for monitoring a live run: the timeline events since a timestamp, plus a cursor to poll with. MCP has no push, so poll again with since=cursor. Optional kinds[] to filter event kinds (e.g. ['verdict','skeptic-escalation','failed']).

Keyword search across one run's artifacts (single-run scope), ranked. mode 'all' (default) = every query word must appear on the line, any order (so 'MYRKUR similar mark conflict' matches a line about all four); 'any' = ≥1 word, ranked by how many; 'phrase' = the exact substring (old behaviour). Returns {artifact, line, score, snippet}. Optional kind to scope to one artifact.

Cross-run search across ALL runs (in-flight + archived) — e.g. 'has the MYRK- root shown up in prior clearances?'. scope: findings (default; the mark/owner/search-term columns — cheapest), audit, key-artifacts (report+registerFindings+commonLaw+narrative), or all-artifacts (full text, most expensive). Same ranked all|any|phrase modes as search. Capped by maxRuns.

The AGPL §13 source offer: this server's name, version, licence, source repository and the COMMIT IT IS RUNNING. Callable by every session kind — the offer is owed to whoever interacts with the service. Reads no run and no account data.

OPS-ONLY. Enqueue a NEW clearance/search run the driver will pick up. Provide markName (or marks[] for a batch) + forwarder (and ideally classes/goods/customer/profileKey/ref). Returns the queue id + slug; the runId/codename is assigned when the runner claims it — poll list_runs (by markName) or run_changes for progress. Spends real money once it runs.

OPS-ONLY. Cancel a run. Pass id to remove a not-yet-claimed queued job (a real cancel, no spend). Pass runId to file a cancel request on a started run. By default the cancel is COOPERATIVE — the sentinel is written and a turn already in flight is allowed to finish, which has no deadline: a reasoning turn can run for tens of minutes. Add immediate:true to also end that turn: it is sent a stop, anything of it still running a few seconds later is killed, and the answer says the turn ended only once it has seen it end. If it could not be ended, the run ends at its next step boundary, and the answer says that instead.

ENGINEERING/AUDIT view — HOW a conclusion was reached; use only when the user asks how/why, not for briefing findings. Walks the full logic flow from any target (a stage, an artifact name, a finding id, or 'verdict') back through the stage that emitted it (and whether a failover occurred), its inputs (with sha-at-consumption vs now), the audit-trail rationale, search terms + record URL, skeptic escalations, and the refutation verdict. Pass shallow:true for a fast skeleton (stage→input lineage + verdict only; skips the findings rebuild and the live provider-usage tally).

DRY-RUN a what-if (no spend), in one of two kinds. kind 'stage' (the default) re-runs a single stage of a LIVE run: what re-runs, the cost prior, what downstream is NOT recomputed, a completeness verdict, and a confirmationToken — pass `stage`, and express the change via instructions (e.g. 'treat ACME as expired') and/or model. kind 'memo' answers a what-if about a DELIVERED report instead: a bounded re-read of that run's archived findings and records under a stated assumption, spending model tokens only — no searching, no register calls, and the report and its archive are never modified. A memo takes no stage; put the reader's own words in `instructions`.

Collect a QUEUED what-if: its state (queued | running | done | failed) and, once done, the diff against the canonical run. Pass runId and the experimentId what_if_run returned; omit experimentId to list every what-if asked of this run. The original run is never modified — the experiment lives in its own sandbox.

EXECUTE a planned what-if (SPENDS tokens / maybe billed calls): re-runs ONE stage in a sandbox (original untouched) and diffs it. Requires the confirmationToken from what_if_plan. Approval-gated — confirm cost before calling. Over the client connector this QUEUES the experiment on the server and returns an experimentId instead of a diff — pass `runId` too, and collect the result with what_if_result.