How Fervion works
Imagine you are working on a project with an AI agent. You ask it to change a few files. It saves several times, tries an approach, backs up, and tries again. Now you have a useful result—but also an important question: what exactly changed, which version is safe, and who decided it was ready?
Fervion is designed for that moment. It keeps the useful speed of a shared project area while making every version understandable, every action attributable, and every release intentional. The terms below give names to the pieces that make that promise work.
This is the main path, not every rule in the system. Scopes control where work can be seen, actors identify who caused it, and undo provides a safe way back when a reviewed change is not the right one.
1. First, Fervion saves the thing itself
When you save a file, Fervion stores the actual content—not just a note saying that the file changed. That saved piece might be a document, image, source file, or any other payload.
Once saved, that piece does not get edited in place. A later edit creates a new saved piece and leaves the old one intact. This is why Fervion can show you what was there before and why an old version does not quietly change beneath you. Internally, these permanent pieces are called objects.
2. Then, it records a version of the project
A project is more than one file, so Fervion can gather the saved pieces into a complete picture: which content belongs at each path, who created the picture, and optionally what the change was for. This complete picture is called a snapshot.
A snapshot is a moment you can return to: “the project as it was after the agent added the tests,” or “the version we reviewed on Tuesday.” A new snapshot does not rewrite an older one; it simply points to the new content.
3. A familiar name points to the current version
People should not have to remember a long identifier for every version. A refis the friendly name—like a branch or main—that points to the snapshot currently in that position.
Two people or agents can work at the same time. Before moving a ref, Fervion checks that you are still changing the version you last saw. If someone got there first, Fervion stops and reports a conflict so you can look at the newer work instead of accidentally replacing it. Fervion uses a small version check to make that handoff safe.
4. Work stays in the right place
Not all work is meant for the same audience. A scope is a visibility boundary: it might hold a private draft, a team area, or a public release. A project can organize people and work, but being a project member does not automatically open every piece of data inside it.
Fervion keeps content in different scopes separate, even when two copies contain the same file. That prevents a private draft from being discoverable just because a similar public file exists.
5. Semantic entries: readable units of work
Real work is messy. There may be ten saves before a change is ready, or an agent may try two approaches before one works. Fervion keeps that detailed activity as it happens instead of pretending the messy parts never existed.
Later, that activity can be gathered into a semantic entry: a readable unit of work such as “Add rate limiting.” The semantic entry is what people review, undo, and promote. The detailed record remains underneath when someone needs to investigate.
6. Review: decide whether the work is ready
A semantic entry gives a reviewer something understandable to look at: what changed, what the change is meant to do, and who or what produced it. Review is the point where another person—or an agreed team process—can inspect that work before it affects a wider audience.
A review can carry discussion, findings, and an approval decision. A passing review is not the same as a ref moving forward: it is evidence that the particular piece of work has passed the checks required for its destination.
7. Promotion: publishing is a decision, not a side effect
When work is ready to leave a private area, Fervion calls that move promotion. For example, a team might promote an approved draft into a public release. Promotion is more than changing a label: the destination receives its own protected copy.
Before that happens, Fervion checks the required review and approval steps and records the move. Agent-produced work follows the same rule. An agent can prepare and explain a change, but it cannot quietly publish it on its own.
8. Undo: return a meaningful change
Because Fervion knows which activity belongs to which piece of work, undocan target a meaningful change instead of blindly reversing the last save. It moves the current ref back to the snapshot from immediately before that work.
The original activity is still recorded, and Fervion checks for newer work before moving the current position. If the position changed in the meantime, it reports a conflict rather than erasing somebody else's progress.
9. Actors: you can tell where the work came from
Fervion treats a person and an AI agent as different kinds of actors, and records who caused each action. For agent work, it also keeps the model, task, and time needed to understand how the change was produced.
If an action cannot be attributed, Fervion rejects it instead of leaving an unexplained hole in the record. That is the promise behind agent-aware collaboration: automation can move quickly, while people can still inspect, review, and reverse its work.