# Versioning & Changesets

Every write you make to Monofile is captured automatically — nothing you change is ever more than a couple of tool calls from being restored.

## What gets captured

- **Per-file versions.** Every content update to an existing file keeps a before-image of what it replaced; file creations keep a create marker. The newest ~20 versions are retained per file, newest first, each with the context of the change that produced it.
- **Named checkpoints.** A `checkpoint` snapshots the *current* content of a file — or an entire folder subtree — under a name you choose. Checkpoints are never auto-pruned, so take one before any large or risky rewrite. Caps: 10 per file, 200 files per folder checkpoint.
- **Changesets.** Each run's changes are grouped into a changeset — the set of files a single API call, run, checkpoint, or revert touched — so the whole unit can be reviewed or undone together.

```bash
curl -X POST "https://www.monofile.ai/api/tools/checkpoint" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Projects", "name": "before refactor"}'
```

## The revert protocol

**Undoing a whole run:** call `list_changesets` to find the changeset (newest first, with summaries and file lists), then `revert_changeset` with its id. This restores every file's pre-change content and deletes files the changeset created.

**Undoing one file:** call `list_versions` on the path, pick a version, then `revert_file`. Use `read_version` to inspect old content first — read it, never reconstruct it from memory.

Reverts are themselves undoable: current content is saved as a new version before any restore, so a wrong revert is just another revert away from fixed.

**On `CONFLICT`:** `revert_changeset` refuses when files were modified *after* the changeset — someone (possibly you, possibly another writer) has since built on that state. Do not immediately retry with `force: true`; confirm with your operator first. Forcing is safe in the recovery sense (current states are versioned first) but may still discard work someone wanted kept.

## Working habits

Checkpoint before risky rewrites, prefer `edit` over full-file `write` so before-images stay meaningful, and reach for `list_changesets` first when asked to undo — it is the fastest route from "that run was wrong" to "it never happened". The tools involved (`list_versions`, `read_version`, `revert_file`, `checkpoint`, `list_changesets`, `revert_changeset`) all follow the standard [[Tools API]] pattern.

## Full reference

Input schemas, scopes, and examples for every versioning tool: `https://www.monofile.ai/skill.md`.