See why a change was made

tovio log --why

Surfaces each change's recorded deliberation rather than just its message: the rationale summary, the decision, the confidence level, the alternatives considered and rejected, and the dead ends.

--why renders the flat list, not the topology graph, and cannot be combined with --graph or --all. Under --json it is purely additive — each commit gains a rationale object.

What a rationale is

A separate, signed, content-addressed object attached to a change — the attested answer to “why”. For a human it is the reasoning given at authoring time. For an agent it includes the instruction it was working from, bound to the commit so it cannot be swapped afterwards.

This matters most six months later, reading a change nobody remembers, and it matters most of all when the author was an agent: a commit message written by a model tells you what it did, and the rationale tells you what it was asked to do.

Which commands write one

Reading a rationale is universal; writing one is a property of the authoring surface. tovio commit has no rationale flag. Rationales are authored by:

• the Node SDK write session and the MCP edge, which attach a structured rationale when an agent commits;
• tovio resolve, which attaches one to the resolving commit — but only alongside a resolution strategy. The rationale flags are metadata on a resolution, so --why requires one of --ours, --theirs, --base, --ai, --keep, --delete, --rename-to or --working-tree. A bare tovio resolve --why "…" is a usage error.

tovio resolve src/auth.rs --ours \  --why "kept ours; theirs reverted the token-expiry fix" \  --rejected "take theirs :: reintroduces the expired-token path" \  --confidence high

A change with no recorded rationale is shown as such, not faked.

Per change

tovio change show <id>tovio change show <id> --diff

The full who, what, when, why and how for one change; --diff also renders the content patch.

Per line

tovio blame <file> --why

Attributes each line to its change and then prints the rationale behind each owning change.

The raw record, not the distillation

tovio log --session <chg>tovio blame <file> --session

A rationale is the distilled reasoning; a session is the raw run record — the originating prompt and the ordered turns. They are independent, and either is useful alone. A session labelled OBSERVED was scraped from an agent runtime's transcript rather than produced under a capability token, and is marked unattested.

Sealed rationales

Where a change touches protected content, its rationale is itself sealed to the same recipients. A rationale you are not entitled to read renders as a locked marker — never as empty text and never as a partial leak.