# Mark the version you trust

> When a document is agreed, or several copies exist, promote the one you trust to canonical so everyone, and every agent, knows which copy is current.

Source: https://avalandra.com/help/mark-the-version-you-trust · Commands checked 2026-11-10

## Have your agent do it

A person can paste this to their agent:

```text
Read https://avalandra.com/help/mark-the-version-you-trust.md and do it with me. Ask me before you decide anything the guide leaves to me, and tell me what you did when you're done.
```

Every document in Avalandra has a standing. Most start as authored, or imported when a connection brought them in. When your team agrees a document is the one to work from, your agent can promote it to canonical. That tells everyone, and every agent that reads the record, which copy to trust.

## When to promote a document

- A brief, plan or spec has been agreed.
- There are several versions of the same thing, and one is current.
- A summary has replaced the raw notes as the thing people should read.

## Promote it

```text
In the [name of your Space] Space, find the documents about [the topic]. Tell me which one looks current and why. When I agree, promote that one to canonical, and suggest what to do with the others.
```

Once it's promoted, archive or mark the other copies so they don't sit beside it looking just as current. See [Archive what's been replaced](https://avalandra.com/help/archive-what-has-been-replaced).

## Before a big change

When a trusted document is about to change a lot, ask your agent to save a named snapshot first. If the change doesn't work out, the document can go back to that snapshot.

```text
Before you edit [the document] in the [name of your Space] Space, save a snapshot of it called "[a name, such as before the March rewrite]". Then make these changes: [the changes].
```

## Questions

### What does canonical mean?

It's the document's standing, and it means this is the version your team has agreed to trust. Your agent can read a document's standing, so it can tell a canonical document from a draft.

### Can there be more than one canonical document in a Space?

Yes, one for each thing. A Space might have a canonical brief, a canonical launch plan and a canonical style guide. What you avoid is two canonical documents about the same thing.

### Can I undo a big edit?

If a snapshot was saved before the edit, the document can be restored to it. Ask your agent to save one before any large change.

## For agents

```
ava document status DOC_ID --space SPACE_ID --json
ava document promote DOC_ID --space SPACE_ID --idempotency-key KEY
ava document version save DOC_ID --space SPACE_ID --idempotency-key KEY
ava document version list DOC_ID --space SPACE_ID
ava document version restore DOC_ID --space SPACE_ID --expected-revision REV --idempotency-key KEY
```

- Read `standing` from `ava document status` before and after promoting.
- Promote only when the person asks, and only the document they agreed.
- Check each command's `--help` for its body fields before writing.
- After promoting, list the other copies of the same content and ask the person what to do with each.
