Skip to the guide

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.

Have your agent do it

Paste this to your agent. It reads this guide and works through it with you.

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

Ask your agent
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.

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.

Ask your agent
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.
Support