# Document versions: replacing a document in place

> Upload a new version of a library document so everything that uses it moves to it with no relinking, and see which version an evaluation was judged against.

- Plans: Core, Team, Enterprise
- Canonical: https://docs.devlin.ai/knowledge/document-versions

When a policy, SOP or handbook changes, upload the new file as a new version of the document that is already in your library. The document keeps its place: every simulation, coach, evaluator and judge that uses it, every knowledge base it is in, and every journey that includes those simulations and coaches move to the new version on their own. Nothing has to be relinked.

## Before you start
- Document versions are part of the library, available on the Core, Team, Enterprise plans.
- Uploading a new version is a Knowledge edit. In an organization where owners and admins have limited who can edit **Knowledge**, other members can see a document's versions but cannot upload one. See [Who can edit the Brain](https://docs.devlin.ai/workspace-and-team/members-and-roles#who-can-edit-the-brain).
- A new version must be a different file. A file whose content is already the version in use changes nothing, and a file that is already another document in your library is refused with a message naming that document.
- Recordings, and course packages with audio or video, cannot get a new version. Add the new file as a separate source instead.

## Steps
1. Open **Brain → Knowledge**.
2. On the document's row, select **Versions**. Once a document has more than one version, the version in use also shows next to its name, for example **v2**.
3. Select **Upload new version** and choose the file.
4. Read the confirmation. It says where the document is used and lists the simulations, coaches and evaluators by name (the first of them when there are many), how many knowledge bases it is in, and, when published items use it, that learners will see the new version there.
5. Select **Upload new version** to confirm.

## Result
The new file is uploaded and processed beside the current version. While it is processing, the dialog shows "New version processing" with the file name, and **the current version keeps answering** everywhere it is used. When processing finishes, everything that uses the document moves to the new version at once: there is never a moment when a simulation, coach or judge has no document to answer from.

A small file is often processed straight away, and the dialog then says the new version is in use. A large file can take several minutes. You can close the dialog: processing continues, and the new version number shows next to the document's name when it is done.

## The version history
The dialog lists every version, newest first, with its file name. The version in use reads "In use"; earlier versions show the date they were uploaded. A document that has never been replaced has one version.

The document's title does not change with a new version. Its file name, size, page count and summary do: a document in the middle size range is summarized again, which uses credits, as for any new upload. See [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases#summaries-on-document-rows).

## If a new version fails
When the new file cannot be processed, the dialog shows a message that starts with "New version failed:" followed by the reason, and says the current version is still in use. Nothing that uses the document changes.

- **Retry** processes the same file again.
- **Discard** removes the failed version. You can then upload a corrected file.

When the new file cannot be read at all (for example a scanned PDF with no text), only **Discard** is offered: processing the same file again would end the same way. The reasons are the ones listed in [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases#failed-and-unsupported-documents).

While a new version is processing, **Discard** cancels it. Until it is in use or discarded, adding the same file to the library as a document of its own, or into a knowledge base, is refused with "This file is a new version of a library document that is still being processed. Wait for it to finish, or discard it in that document's Versions dialog, then add the file again." Only one new version can be processing at a time: uploading another is refused with "A new version of this document is already processing. Wait for it to finish, or discard it, before uploading another."

## Which version an evaluation was judged against
When a simulation's or an evaluator's judge uses reference materials, each evaluation records which version of each document its reference passages came from. Opening the attempt in a simulation's **Results**, or a submission in an evaluator's results, shows a "Judged against:" line, for example "Refill SOP v3". Learners never see it.

Evaluations made before a document's new version keep the version they were judged against, so you can tell results judged against an old SOP from results judged against the new one. Evaluations made before this record existed show no such line. See [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring#reference-materials-for-the-judge).

## Limits and storage
- While a new version is processing, its file counts toward the workspace's content allowance next to the current version. When it replaces the current version, the library's document count does not change. A new version is refused when the size it adds would take the workspace past its storage limit.
- Earlier versions' files are kept for 90 days after they are replaced, then deleted. The version history itself is kept for as long as the document exists.
- Deleting the document deletes every version.

## Ask devlin and AI tools over MCP
- In Ask devlin, attach the updated file in the chat and ask to replace the document with it. devlin uses `replace_document`, which applies at once unless you review every edit, and tells you where the document is used. The attachment becomes the new version, so it no longer appears in the library as a document of its own.
- An AI tool connected through the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) uploads the new file with `create_source_upload` and `add_source` (build only), then calls `replace_document` with the library document's id and the new file's id. It needs write access. When published simulations, coaches or evaluators use the document, the tool has to confirm the change explicitly, and when the workspace requires approval for live changes the replacement waits for an owner or admin to approve it.

All three, the Knowledge tab, Ask devlin and MCP, replace a document the same way.

## Related
- [Knowledge bases: uploading and managing documents](https://docs.devlin.ai/knowledge/knowledge-bases)
- [Grounding simulations and coaches in a knowledge base](https://docs.devlin.ai/knowledge/ground-simulations-and-coaches-in-knowledge)
- [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring)
- [Source materials](https://docs.devlin.ai/knowledge/source-materials)