Changing a file
Connect never edits a file in place. modify_file reads the version you point at, applies the change and writes the result as the next version in the chain. The version you started from keeps its bytes, its place in the history and every audit entry that ever referred to it, so an answer given last month still points at what was actually read.
The rule, and the reason for it#
Overwriting is cheap until the day somebody asks what the document said before. An agent that edits files in place destroys the only evidence that would settle the question, and it does it silently, in the ordinary course of being helpful. Connect writes a new version instead, every time, with no mode that turns this off.
The cost is a longer list under a file. The gain is that every claim anyone made about that document remains checkable: the citation names a version, and that version still exists to be opened.
What the earlier version keeps#
| Thing | The version you started from | The version Connect wrote |
|---|---|---|
| Contents | Unchanged, byte for byte | The changed document |
| Position in the chain | Kept, in order | Appended after it |
| Provenance | Whatever produced it originally | The request, the tool and the person who ran it |
| Audit entries | Kept — an entry is never rewritten to point somewhere else | A new entry for this change |
| Answers that cited it | Still refer to the text they were given | Not retrospectively attached to older answers |
Asking for a change#
Name the file and say what should be different. Point at the version if it is not the latest.
Result Connect reads that exact version rather than assuming the newest one is what you meant.
Read the proposal. It says what will change and which file it starts from.
Result A change aimed at the wrong document is caught here, where it costs nothing.
Run it.
Result A new version is written, the previous one stays exactly as it was, and the audit records the request behind the change.
Check the result in preview.
Result You are looking at the new version, and the earlier one is still one click away if the change went too far.
There is no undo in the sense of erasing what happened, because nothing was erased. Going back is opening the earlier version — and if you want it to be the current one, that is another change, which produces another version. The chain grows forwards only.
What a change will not do#
- Change the format. A change applies to the document as it is. Producing the same content in a different format is a new file, not a new version of this one.
- Invent a value that was missing. The same rule that leaves a gap in a document Connect creates applies to one it changes.
- Touch a linked record. Changing an attached quotation does not move the deal or update the company. Records change through their own services — see editing in the grid.
- Reach outside the workspace.
modify_fileoperates on files in your workspace only, under the same isolation as every other record.
Where it goes wrong#
- The wrong version was changed
- You asked while looking at an older one. The fix is another change from the right version; nothing was lost.
- The file cannot be parsed to change it
- The stored file failed safe parsing on the way in, or is an image. Connect refuses rather than producing a damaged document — parsing a file safely covers the refusals.
- The change is bigger than expected
- A vague instruction gives the model room. Ask for the specific section, and compare versions afterwards.
- Two people changed the same file
- Both changes exist, in order. Neither overwrote the other, but the later one was applied to the earlier result, which is worth reading before assuming they merged.
Questions#
Can I stop Connect making a new version and just edit the file?
No, and the absence of that setting is deliberate. Every change is a version so that provenance and audit stay true for every file in the workspace, rather than for the files somebody remembered to protect.
Does the old version still count against my storage?
Both versions exist, so both are stored. What a plan allows is a commercial question rather than a file-service one, and it is answered on the plan and usage screen rather than here.
If somebody quoted the document to a customer, which version did they quote?
The one that existed when they read it, and the audit trail says which that was. That is the whole point of refusing to overwrite: the question has an answer months later, when nobody remembers the conversation.