onetrace-explain

A suggested explanation of a onetrace comparison: AI-generated, may be wrong, and checked against the record before anyone reads it. Never a verdict: onetrace's verdicts and exit codes are what they are without it, and its exit codes say nothing about the runs. Don't use it as a CI gate.

onetrace localize runs/a runs/b --for answer --out report
onetrace-explain report --dry-run          # the packet exactly as it would be sent; nothing sent
onetrace-explain report --model anthropic:<model name>

• What is sent: a packet built from the report and the two runs' receipts: verdicts, stage names and edges, outcome classes, digests and sizes, instrument names and versions, and the constants that differ with both values (--redact NAME sends a name and digest only). Kept text only with --include-text. A constant's value goes as the run recorded it, a path or a token included; --redact NAME keeps it out. Never this machine's own paths, an environment variable, the model key, a signing key or an anchor's proof. The first send of a kind of item to an endpoint asks first (--yes for scripts).

• The model: yours, named in ~/.config/onetrace/explain.toml:

  [model]
  provider = "anthropic"          # or "openai" (any OpenAI-compatible endpoint, local ones too)
  name = "<model name>"
  key_env = "ANTHROPIC_API_KEY"   # the variable holding the key; the key is never written anywhere
  # base_url = "http://localhost:8000/v1"   # for an openai-compatible server
  

• The post-check, with no model: a claim is dropped when it cites nothing, cites what the packet doesn't hold, quotes a value its cites don't hold, or says what caused a difference. What's shown says how many were dropped, and why.

• Checks, not conclusions: each suggestion comes with onetrace commands to run. A lead is confirmed or ruled out only by what those report.

• Recorded: every explanation is a onetrace run of its own, under <out>/explain/<run id>/, which onetrace-verify checks like any run.