Version diff
What this page is — the capability that reports what actually changed between two versions of a document in business terms, ignoring the rewording that changes nothing.
What it is for — so an incoming round is read starting from the three clauses that moved, rather than from page one of forty reformatted pages.
The problem it solves — reviewers re-read whole documents to find the three clauses that changed, and miss one.
Route: /org/papers/documents/<document>/ai → Negotiate → Version diff ·
Permission: Use AI drafting/extraction/Q&A for documents. ·
Utility: papers_semantic_diff · Cost: 450 credits estimated, 1,800 maximum.
1. What it is
A coloured text diff shows every word that moved, which on a reformatted round is most of them. This does the opposite: it reads the prior version and the current one and reports only changes of meaning.
| Reports | Ignores |
|---|---|
| A clause added or gutted | "shall" changed to "will" |
| A notice period shortened | A paragraph renumbered |
| A cap lowered | A defined term capitalised differently |
| A date moved | Wholesale reformatting |
Every change carries the shortest quote from each side, so you can see exactly what moved without opening either version.
| Reads | Tone | |
|---|---|---|
| Version diff | Prior version vs current | Neutral — shareable |
| Shadow redline | Their round vs your text | Adversarial — internal only |
| Comparing versions | The same two versions | A visual text diff, not an analysis |
Version diff and Shadow redline read the same two documents and answer different questions: what changed against what it costs you. Run the diff first; it is the one you can forward.
2. Why you would use it
The risk in a returned round is not the change you argue about. It is the change nobody notices because it arrived inside a reformat.
- It finds the shortened cure period. A notice window cut from 30 days to 10, buried in a re-numbered section, is invisible to a reader and obvious to this.
- It gives you reading order. Ordered highest severity first, so the fifteen minutes you have goes to the change that shifts the deal most.
plain_summarysays who gained. A short paragraph a non-lawyer can read — who conceded, who gained, what to watch. That is the update you send to the deal team.- It cuts the cosmetic noise entirely. The reason people stop reading text diffs is that the signal-to-noise ratio collapses after round two.
- An empty result is informative.
changes[]empty means nothing meaningful moved — the round was formatting. That is worth knowing in ten seconds rather than an hour.
3. What you provide
Nothing. It is a one-press capability with no parameters, and it does not ask you to pick files.
| Input | Required | Notes |
|---|---|---|
| — | — | It compares against the immediately prior version, automatically |
The document must have one — a saved earlier version, or the counterparty's previous round. With only one version there is nothing to diff. If the earlier round exists outside Papers, import or save it first, then run.
You cannot choose which versions to compare. It is always current against immediately prior, which is why the running advice in §7 matters.
4. What it reads automatically
| Read from the document | Used for |
|---|---|
| Current text — the full body of the version you have open | One side of the comparison |
| Prior version text — the immediately preceding round, pulled automatically | The other side |
| Title & family — e.g. "Supply Agreement" | Judging what counts as material in this kind of document |
| Parties — everyone named | Who gained and who conceded, in impact |
5. What you get back
changes[], ordered highest severity first.
| Field | Type | Values | Means |
|---|---|---|---|
summary | string, one sentence | — | What changed |
category | enum | clause, term, value, structure | What kind of change it is |
impact | string | — | What it means commercially or legally for the parties |
severity | enum | high, medium, low | How materially it shifts the deal |
from_excerpt | string | empty if the content is new | Shortest quote from the prior version |
to_excerpt | string | empty if the content was removed | Shortest quote from the current version |
Plus plain_summary — a short paragraph a non-lawyer can read. When nothing meaningful changed,
changes[] is empty and plain_summary says so.
The two excerpt fields are a compact way to read a deletion or an insertion: an empty
from_excerpt means it is new; an empty to_excerpt means it is gone.
6. Worked example
A round arrives on a supply agreement. It is visually different throughout — the counterparty reformatted to their house style — so a text diff is unreadable.
Input: none.
Top entry of changes[]:
Payment window shortened category:
value· severity:highsummary: Payment terms tightened from Net 45 to Net 15 days. impact: Cuts our working-capital float by a month and raises the risk of late-fee triggers on every invoice. from_excerpt: "within forty-five (45) days" to_excerpt: "within fifteen (15) days"
What the reviewer does with it. Two quoted fragments, nine words between them, and the change is
proven — no need to open either version to confirm it. The impact line is what goes to finance,
because a thirty-day swing in working capital is their decision, not the reviewer's.
The same run returned two further changes, both low and both structure: sections renumbered. The
reformatting that made the text diff useless produced exactly two lines of noise here.
7. Running it
- Open the document in Orbit Papers on the newest version.
- Open the AI Assistant drawer, or go to the document's AI workspace.
- Choose Version diff under Negotiate.
- It compares against the immediately prior version automatically — no files to pick.
- The change list and
plain_summaryappear in a result tab and are saved to the document.
It compares against the immediately prior version only. Let three rounds stack up and the diff covers the last one, not all three — the changes from rounds four and five are simply not in the comparison. Diffing each round as it arrives is the only way to see everything.
Available for auto-run from the type's AI Config tab. on_round is the natural event, and it
enforces the discipline above automatically. See AI configuration.
8. The admin contract
| Must be true | Where | What happens if it is not |
|---|---|---|
| Your role holds Use AI drafting/extraction/Q&A for documents. | Role editor | The AI Assistant button does not appear |
The papers_semantic_diff utility is active | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | Absent from Negotiate, with no error |
papers.ai_monthly_credit_cap not yet reached | System Config | "monthly AI credit cap reached: n of n credits used this month" |
| Versioning is enabled on the document type | Behaviour settings | No prior version is ever kept, so the diff has nothing to compare against — on any round |
| Each counterparty round is saved as a version | Redlines and rounds | Rounds collapse into one version and intermediate changes become invisible |
The last two rows are the whole prerequisite. This capability is a function of your versioning discipline more than of any AI setting.
For a confidential document, auto-run is default-denied — a platform administrator must set
papers.ai_confidential_cloud to the literal allow, and the block appears only in the server log.
A manual press still works, and where a local model key is configured the run is forced on-prem and
audited on the timeline as ai_local_routed.
9. Don't confuse this with…
| Comparing versions | The visual text diff. This is the analysis of it |
| Shadow redline | Adversarial and internal-only. This is neutral and shareable |
| Redline grade | Judges one proposed edit against your playbook. This reports all changes |
| Negotiation analytics | Counts rounds and topics. This reads inside one round |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| "Nothing to diff" | The document has only one version (§3). Save or import the earlier round first |
changes[] is empty after a round | Nothing material moved — the round was formatting. plain_summary says so |
| A change I know about is missing | Several rounds stacked up; it compares only against the immediately prior version (§7) |
from_excerpt is empty | The content is new — there is no prior wording to quote |
to_excerpt is empty | The content was removed |
| Cosmetic changes are being reported | Renumbering shows as category: structure, usually low. That is the floor of what it reports, not noise |
| The severity feels wrong for our deal | Severity is judged against the document's own values. A change that matters to you commercially may be small in the document's terms |
| The capability is missing from Negotiate | Role lacks Use AI drafting/extraction/Q&A for documents., or the utility is off for the organisation (§8). The document type does not gate it — AI Config controls auto-run only |