Comparing versions
What this page is — finding exactly what changed between two versions of a document, whether the other side sent it back or a colleague edited it.
What it is for — so a returned document is reviewed for what changed, not re-read from page one.
The problem it solves — the other side's "few small tweaks" are found by reading forty pages, and the one that reverses a liability is the one missed.
Route: the Version history panel on /org/papers/documents/<document> · Permission:
View this project's documents.
1. What it is
Every meaningful moment in a document's life creates an immutable version. A version is a snapshot of the content blocks and field values. Comparing two versions can be done two ways, and they answer different questions:
| Version history diff | Version diff (AI) | |
|---|---|---|
| Reports | Exactly which blocks and fields changed, with old and new values | What the changes mean |
| Cost | Free | AI credits |
| Misses nothing textual | Yes | No — it summarises |
| Tells you a one-word change reverses liability | No — it shows the word | Yes |
| Use it to | Check precisely, or evidence a change | Triage a long return quickly |
Use both on an important return: the AI diff to find what matters, and the exact diff to confirm it.
Kinds of version
| Kind | Created when |
|---|---|
| draft | Author checkpoints, and a new draft after accepting a redline |
| finalized | The document is sealed |
| counterparty round | The counterparty sends it back from the portal |
| amended | An amendment is sealed |
2. Why you would use it
- "A few small tweaks" gets checked, not trusted. A forty-page agreement returned with an unmarked change to a notice period is the classic expensive miss.
- Reviews take minutes instead of an afternoon. Reading ten changed blocks instead of forty pages keeps the review honest because it stays short.
- Field changes are unambiguous.
contract_value: 40000 → 45000cannot be misread the way a changed paragraph can. - You can prove what was in force. Make effective records which version legally applies, and the verification page uses that record.
3. Step by step
- Open the document's Version history panel. Versions are listed newest first, with kind, label, author and time. Changes made by automation show System — no signed-in user.
- Expand a version. Its diff against the previous version loads.
- Read the two sections:
- Content blocks — each marked added, removed or modified, with from and to text.
- Fields — each changed field with its old and new value.
- To keep a snapshot before risky edits, click Checkpoint and add a note. You will see "Checkpoint saved".
- To go back, Restore an earlier version. Restoring copies it forward as new content, so history is never rewritten.
- To record which version is legally in force, choose Make effective. As the confirmation says: "This records which version is currently in force. It does not change any content."
4. Field reference — the diff
| Part | Matching rule | Shows |
|---|---|---|
| Block change | Blocks matched by block id, recursing into nested blocks | added, removed or modified, with from and to text |
| Field change | Fields matched by key | Old and new raw values; a field missing on one side shows as null |
| Header | — | The from and to version labels |
What the matching rules mean in practice
| You did | The diff shows |
|---|---|
| Edited words inside a clause | One modified block with old and new text |
| Deleted a clause and wrote a new one in its place | One removed plus one added — not a modification |
| Moved a block to another section, keeping its id | Its content is unchanged, so no text change is reported. Read the structure yourself if order matters |
Changed a number field from 45000 to the text "45000" | A change — values are compared exactly as stored |
| Cleared a field | New value null |
5. Choosing which versions to compare
| Question | Compare |
|---|---|
| What did the counterparty change this round? | The latest counterparty round with the version you sent |
| What changed since legal approved it? | Current with the version approval saw |
| What did the amendment change? | amended with the original finalized |
| Which clause text applied on a given date? | The version made effective at that date |
Both tools compare adjacent versions only: the panel's expand action compares with the previous version, and the AI Version diff always compares current with immediately prior. To see everything since the version you sent three rounds ago, expand each round in turn. Or ask for each round to be diffed as it arrives, so changes never stack up unread.
6. Worked example
Kestrel Foods returns Distribution Agreement DA-2026-012 as round 2, saying "minor clarifications".
-
The owner expands counterparty round 2. The diff against v1.3, the version sent, shows:
Change Detail Modified — clause 6.1 "within 30 days of invoice" → "within 60 days of invoice" Modified — clause 14.2 "either party may terminate" → "the Distributor may terminate" Field exclusivity_territory: "South India" → "India"Added Clause 14.5 Termination for convenience -
The AI version diff confirms clause 14.2 now gives only Kestrel a termination right. That is a material shift worded as a clarification.
-
The owner runs Fairness / balance, which now leans towards Kestrel, and raises all four points in round 3.
-
After signature, the owner makes the signed version effective. Old copies of v1.3 now show superseded when checked.
7. The admin contract
| What must be configured | Otherwise |
|---|---|
| Allows versioning on the type (on by default) | No history accumulates to compare |
| Templates built from blocks with stable ids | Edits appear as remove-and-add pairs |
| Structured fields for key commercial terms | Changes to values are buried in paragraph text |
| AI enabled with credits, for the AI diff | Only the exact diff is available |
8. Downstream
- Make effective decides what the verification page calls current. A copy of any other version reads as superseded.
- Restores and checkpoints appear in Activity.
- Rounds feed negotiation analytics.
9. Don't confuse this with…
| Redlines and rounds | Proposals not yet applied. A diff shows what was applied |
| Cross-document consistency | Compares different documents in a family |
| Preview and versions | The author's view of versions while drafting |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| Only one version, nothing to expand | Versioning is off on the type, or nothing has been checkpointed or sent |
| "Failed to compute diff" | One of the versions could not be loaded — refresh; if it persists, the version may predate its type's current structure |
| A small edit shows as a whole clause removed and added | The block was deleted and recreated, so its id changed |
| The diff is empty but the PDF looks different | Only layout or branding changed — the diff compares content and fields |
| Verification says superseded for a version you consider current | Another version was made effective |